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

package/dist/src/FlinkApp.js

@@ -50,7 +50,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FlinkApp = exports.autoRegisteredJobs = exports.autoRegisteredRepos = exports.autoRegisteredHandlers = exports.expressFn = void 0;
+exports.FlinkApp = exports.autoRegisteredServices = 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"));
@@ -63,9 +63,16 @@ var toad_scheduler_1 = require("toad-scheduler");
 var uuid_1 = require("uuid");
 var FlinkErrors_1 = require("./FlinkErrors");
 var FlinkHttpHandler_1 = require("./FlinkHttpHandler");
+var LeaderElection_1 = require("./LeaderElection");
 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 initLog = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.init");
+var perfLog = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.perf");
+var schedulerLog = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.scheduler");
 var ajv = new ajv_1.default();
 (0, ajv_formats_1.default)(ajv);
 var defaultCorsOptions = {
@@ -93,8 +100,24 @@ exports.autoRegisteredRepos = [];
  * 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 = [];
+/**
+ * This will be populated at compile time when the apps services
+ * are picked up by TypeScript compiler
+ */
+exports.autoRegisteredServices = [];
 var FlinkApp = /** @class */ (function () {
     function FlinkApp(opts) {
+        var _a, _b;
         this.handlers = [];
         this.started = false;
         this.debug = false;
@@ -102,10 +125,18 @@ var FlinkApp = /** @class */ (function () {
         this.routingConfigured = false;
         this.disableHttpServer = false;
         this.repos = {};
+        this.services = {};
+        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();
+        // Load config file and initialize logging
+        var loadFlinkConfig = require("./utils/loadFlinkConfig").loadFlinkConfig;
+        var flinkConfig = loadFlinkConfig();
+        FlinkLogFactory_1.FlinkLogFactory.configure(flinkConfig === null || flinkConfig === void 0 ? void 0 : flinkConfig.logging);
         this.name = opts.name;
         this.port = opts.port || 3333;
         this.dbOpts = opts.db;
@@ -124,6 +155,13 @@ var FlinkApp = /** @class */ (function () {
         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));
+        }
+        // Register global agent observer if configured
+        this.agentObserver = (_b = opts.ai) === null || _b === void 0 ? void 0 : _b.observer;
     }
     Object.defineProperty(FlinkApp.prototype, "ctx", {
         get: function () {
@@ -137,33 +175,43 @@ var FlinkApp = /** @class */ (function () {
     });
     FlinkApp.prototype.start = function () {
         return __awaiter(this, void 0, void 0, function () {
-            var startTime, offsetTime, _i, _a, type, _b, _c, plugin, db;
+            var startTime, 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 = 0;
+                        dbStartTime = Date.now();
                         return [4 /*yield*/, this.initDb()];
                     case 1:
                         _e.sent();
-                        if (this.debug) {
-                            offsetTime = Date.now();
-                            FlinkLog_1.log.bgColorLog("cyan", "Init db took ".concat(offsetTime - startTime, " ms"));
-                        }
+                        perfLog.debug("Init db took ".concat(Date.now() - dbStartTime, "ms"));
+                        contextStartTime = Date.now();
                         return [4 /*yield*/, this.buildContext()];
                     case 2:
                         _e.sent();
-                        if (this.debug) {
-                            FlinkLog_1.log.bgColorLog("cyan", "Build context took ".concat(Date.now() - offsetTime, " ms"));
-                            offsetTime = Date.now();
-                        }
-                        if (this.isSchedulingEnabled) {
+                        perfLog.debug("Build context took ".concat(Date.now() - contextStartTime, "ms"));
+                        toolsStartTime = Date.now();
+                        return [4 /*yield*/, this.registerAutoRegisterableTools()];
+                    case 3:
+                        _e.sent();
+                        perfLog.debug("Register tools took ".concat(Date.now() - toolsStartTime, "ms"));
+                        agentsStartTime = Date.now();
+                        return [4 /*yield*/, this.registerAutoRegisterableAgents()];
+                    case 4:
+                        _e.sent();
+                        perfLog.debug("Register agents took ".concat(Date.now() - agentsStartTime, "ms"));
+                        agentInitStartTime = Date.now();
+                        return [4 /*yield*/, this.initializeAgents()];
+                    case 5:
+                        _e.sent();
+                        perfLog.debug("Initialize agents took ".concat(Date.now() - agentInitStartTime, "ms"));
+                        if (this.isSchedulingEnabled && !this.leaderElectionConfig) {
                             this.scheduler = new toad_scheduler_1.ToadScheduler();
                         }
-                        else {
-                            FlinkLog_1.log.info("🚫 Scheduling is disabled");
+                        else if (!this.isSchedulingEnabled) {
+                            schedulerLog.info("Scheduling is disabled");
                         }
                         if (!this.disableHttpServer) {
                             this.expressApp = (0, express_1.default)();
@@ -183,46 +231,53 @@ var FlinkApp = /** @class */ (function () {
                                 next();
                             });
                         }
+                        pluginsStartTime = Date.now();
                         _b = 0, _c = this.plugins;
-                        _e.label = 3;
-                    case 3:
-                        if (!(_b < _c.length)) return [3 /*break*/, 9];
+                        _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*/, 5];
+                        if (!plugin.db) return [3 /*break*/, 8];
                         return [4 /*yield*/, this.initPluginDb(plugin)];
-                    case 4:
-                        db = _e.sent();
-                        _e.label = 5;
-                    case 5:
-                        if (!plugin.init) return [3 /*break*/, 7];
-                        return [4 /*yield*/, plugin.init(this, db)];
-                    case 6:
-                        _e.sent();
-                        _e.label = 7;
                     case 7:
-                        FlinkLog_1.log.info("Initialized plugin '".concat(plugin.id, "'"));
+                        db = _e.sent();
                         _e.label = 8;
                     case 8:
-                        _b++;
-                        return [3 /*break*/, 3];
-                    case 9: return [4 /*yield*/, this.registerAutoRegisterableHandlers()];
-                    case 10:
+                        if (!plugin.init) return [3 /*break*/, 10];
+                        return [4 /*yield*/, plugin.init(this, db)];
+                    case 9:
                         _e.sent();
-                        if (this.debug) {
-                            FlinkLog_1.log.bgColorLog("cyan", "Register handlers took ".concat(Date.now() - offsetTime, " ms"));
-                            offsetTime = Date.now();
+                        _e.label = 10;
+                    case 10:
+                        initLog.info("Initialized plugin '".concat(plugin.id, "'"));
+                        _e.label = 11;
+                    case 11:
+                        _b++;
+                        return [3 /*break*/, 6];
+                    case 12:
+                        if (this.plugins.length > 0) {
+                            perfLog.debug("Initialize plugins took ".concat(Date.now() - pluginsStartTime, "ms (").concat(this.plugins.length, " plugins)"));
                         }
-                        if (!this.isSchedulingEnabled) return [3 /*break*/, 12];
+                        handlersStartTime = Date.now();
+                        return [4 /*yield*/, this.registerAutoRegisterableHandlers()];
+                    case 13:
+                        _e.sent();
+                        perfLog.debug("Register handlers took ".concat(Date.now() - handlersStartTime, "ms"));
+                        if (!this.isSchedulingEnabled) return [3 /*break*/, 17];
+                        if (!this.leaderElectionConfig) return [3 /*break*/, 15];
+                        return [4 /*yield*/, this.startLeaderElection()];
+                    case 14:
+                        _e.sent();
+                        return [3 /*break*/, 17];
+                    case 15:
+                        jobsStartTime = Date.now();
                         return [4 /*yield*/, this.registerAutoRegisterableJobs()];
-                    case 11:
+                    case 16:
                         _e.sent();
-                        if (this.debug) {
-                            FlinkLog_1.log.bgColorLog("cyan", "Register jobs took ".concat(Date.now() - offsetTime, " ms"));
-                            offsetTime = Date.now();
-                        }
-                        _e.label = 12;
-                    case 12:
+                        perfLog.debug("Register jobs took ".concat(Date.now() - jobsStartTime, "ms"));
+                        _e.label = 17;
+                    case 17:
                         // 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 () {
@@ -234,7 +289,7 @@ var FlinkApp = /** @class */ (function () {
                             _this.routingConfigured = true;
                         });
                         if (this.disableHttpServer) {
-                            FlinkLog_1.log.info("🚧 HTTP server is disabled, but flink app is running");
+                            initLog.info("🚧 HTTP server is disabled, but flink app is running");
                             this.started = true;
                         }
                         else {
@@ -243,6 +298,8 @@ var FlinkApp = /** @class */ (function () {
                                 _this.started = true;
                             });
                         }
+                        totalStartTime = Date.now() - startTime;
+                        perfLog.info("\u2713 FlinkApp started in ".concat(totalStartTime, "ms"));
                         return [2 /*return*/, this];
                 }
             });
@@ -255,12 +312,24 @@ var FlinkApp = /** @class */ (function () {
                 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()];
+                        if (!this.leaderElection) return [3 /*break*/, 2];
+                        return [4 /*yield*/, this.leaderElection.stop()];
                     case 1:
                         _a.sent();
                         _a.label = 2;
                     case 2:
+                        if (!this.scheduler) return [3 /*break*/, 4];
+                        return [4 /*yield*/, this.scheduler.stop()];
+                    case 3:
+                        _a.sent();
+                        _a.label = 4;
+                    case 4:
+                        if (!this.allInstanceScheduler) return [3 /*break*/, 6];
+                        return [4 /*yield*/, this.allInstanceScheduler.stop()];
+                    case 5:
+                        _a.sent();
+                        _a.label = 6;
+                    case 6:
                         if (this.expressServer) {
                             return [2 /*return*/, new Promise(function (resolve, reject) {
                                     var int = setTimeout(function () {
@@ -285,7 +354,6 @@ var FlinkApp = /** @class */ (function () {
      * 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");
         }
@@ -304,28 +372,37 @@ var FlinkApp = /** @class */ (function () {
             // 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"));
         }
+        // Use direct schemas from routeProps if provided, otherwise fall back to manifest lookup
+        var reqSchema = routeProps.reqSchema;
+        var resSchema = routeProps.resSchema;
+        var queryMetadata = [];
+        var paramsMetadata = [];
+        if (!reqSchema || !resSchema) {
+            var schemaManifest = this.loadSchemaManifest();
+            var metadata = handler.__file ? schemaManifest.handlers[handler.__file] : undefined;
+            if (!reqSchema)
+                reqSchema = this.resolveSchema(metadata === null || metadata === void 0 ? void 0 : metadata.reqSchemaName);
+            if (!resSchema)
+                resSchema = this.resolveSchema(metadata === null || metadata === void 0 ? void 0 : metadata.resSchemaName);
+            queryMetadata = (metadata === null || metadata === void 0 ? void 0 : metadata.queryMetadata) || [];
+            paramsMetadata = (metadata === null || metadata === void 0 ? void 0 : metadata.paramsMetadata) || [];
+        }
         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,
+                reqSchema: reqSchema,
+                resSchema: resSchema,
             },
-            queryMetadata: handler.__query || [],
-            paramsMetadata: handler.__params || [],
+            queryMetadata: queryMetadata,
+            paramsMetadata: paramsMetadata,
         };
-        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;
+        var method = routeProps.method, streamFormat = routeProps.streamFormat;
         if (!method) {
             FlinkLog_1.log.error("Route ".concat(routeProps.path, " is missing http method"));
         }
@@ -336,45 +413,77 @@ var FlinkApp = /** @class */ (function () {
             }
             var validateReq_1;
             var validateRes_1;
+            // Select AJV instance (use schemaAjv for v2.0 manifests, fallback to global ajv)
+            var ajvInstance = this.schemaAjv || ajv;
             // 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);
+                // For v2.0 manifests with $id, use getSchema() if available
+                if (schema.reqSchema.$id && this.schemaAjv) {
+                    validateReq_1 = this.schemaAjv.getSchema(schema.reqSchema.$id);
+                    if (!validateReq_1) {
+                        FlinkLog_1.log.warn("Schema ".concat(schema.reqSchema.$id, " not found in AJV registry, compiling inline"));
+                        validateReq_1 = ajvInstance.compile(schema.reqSchema);
+                    }
+                }
+                else {
+                    validateReq_1 = ajvInstance.compile(schema.reqSchema);
+                }
             }
-            // Compile response schema if validation mode requires it
-            if (schema.resSchema && validationMode !== FlinkHttpHandler_1.ValidationMode.SkipValidation && validationMode !== FlinkHttpHandler_1.ValidationMode.ValidateRequest) {
-                validateRes_1 = ajv.compile(schema.resSchema);
+            // 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) {
+                // For v2.0 manifests with $id, use getSchema() if available
+                if (schema.resSchema.$id && this.schemaAjv) {
+                    validateRes_1 = this.schemaAjv.getSchema(schema.resSchema.$id);
+                    if (!validateRes_1) {
+                        FlinkLog_1.log.warn("Schema ".concat(schema.resSchema.$id, " not found in AJV registry, compiling inline"));
+                        validateRes_1 = ajvInstance.compile(schema.resSchema);
+                    }
+                }
+                else {
+                    validateRes_1 = ajvInstance.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, handlerRes, err_1, errorResponse, result, valid, formattedErrors;
-                return __generator(this, function (_c) {
-                    switch (_c.label) {
+                var valid, formattedErrors, errorResponse, data, normalizedQuery, _i, _a, _b, key, value, stream, handlerRes, flinkReq_1, err_1, errorResponse, detail, errorResponse, valid, formattedErrors, errorResponse;
+                var _this = this;
+                var _c;
+                return __generator(this, function (_d) {
+                    switch (_d.label) {
                         case 0:
                             if (!routeProps.permissions) return [3 /*break*/, 2];
                             return [4 /*yield*/, this.authenticate(req, routeProps.permissions)];
                         case 1:
-                            if (!(_c.sent())) {
+                            if (!(_d.sent())) {
                                 return [2 /*return*/, res.status(401).json((0, FlinkErrors_1.unauthorized)())];
                             }
-                            _c.label = 2;
+                            _d.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,
-                                            },
-                                        })];
+                                    errorResponse = {
+                                        status: 400,
+                                        error: {
+                                            id: (0, uuid_1.v4)(),
+                                            title: "Bad request",
+                                            detail: formattedErrors,
+                                        },
+                                    };
+                                    this.invokeOnError(errorResponse, req, method, routeProps.path);
+                                    return [2 /*return*/, res.status(400).json(errorResponse)];
                                 }
                             }
-                            if (routeProps.mockApi && schema.resSchema) {
+                            // 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({
@@ -402,20 +511,47 @@ var FlinkApp = /** @class */ (function () {
                                 }
                                 req.query = normalizedQuery;
                             }
-                            _c.label = 3;
+                            stream = streamFormat ? StreamWriterFactory_1.StreamWriterFactory.create(res, streamFormat) : undefined;
+                            _d.label = 3;
                         case 3:
-                            _c.trys.push([3, 5, , 6]);
-                            return [4 /*yield*/, handler({
-                                    req: req,
-                                    ctx: this.ctx,
-                                    origin: routeProps.origin,
-                                })];
+                            _d.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:
-                            // 👇 This is where the actual handler gets invoked
-                            handlerRes = _c.sent();
+                            handlerRes = _d.sent();
                             return [3 /*break*/, 6];
                         case 5:
-                            err_1 = _c.sent();
+                            err_1 = _d.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) {
@@ -434,44 +570,64 @@ var FlinkApp = /** @class */ (function () {
                                 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));
-                                }
-                            }
+                            this.invokeOnError(errorResponse, req, method, routeProps.path);
                             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({
+                                if (handlerRes.data === undefined) {
+                                    if (handlerRes.status !== 204) {
+                                        detail = "Response schema is defined but handler returned no data";
+                                        FlinkLog_1.log.warn("[".concat(req.reqId, "] ").concat(methodAndRoute_1, ": Bad response - ").concat(detail));
+                                        errorResponse = {
+                                            status: 500,
+                                            error: { id: (0, uuid_1.v4)(), title: "Bad response", detail: detail },
+                                        };
+                                        this.invokeOnError(errorResponse, req, method, routeProps.path);
+                                        return [2 /*return*/, res.status(500).json(errorResponse)];
+                                    }
+                                }
+                                else {
+                                    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));
+                                        errorResponse = {
                                             status: 500,
                                             error: {
                                                 id: (0, uuid_1.v4)(),
                                                 title: "Bad response",
                                                 detail: formattedErrors,
                                             },
-                                        })];
+                                        };
+                                        this.invokeOnError(errorResponse, req, method, routeProps.path);
+                                        return [2 /*return*/, res.status(500).json(errorResponse)];
+                                    }
                                 }
                             }
                             res.set(handlerRes.headers);
+                            if (routeProps.responseType) {
+                                return [2 /*return*/, res
+                                        .status(handlerRes.status || 200)
+                                        .type(routeProps.responseType)
+                                        .send(handlerRes.data)];
+                            }
+                            if (((_c = handlerRes.error) === null || _c === void 0 ? void 0 : _c.meta) !== undefined) {
+                                try {
+                                    JSON.stringify(handlerRes.error.meta);
+                                }
+                                catch (e) {
+                                    FlinkLog_1.log.warn("[".concat(handlerRes.reqId, "] error.meta stripped from error ").concat(handlerRes.error.id, ": not JSON-serializable (").concat(e.message, ")"));
+                                    delete handlerRes.error.meta;
+                                }
+                            }
                             res.status(handlerRes.status || 200).json(handlerRes);
                             return [2 /*return*/];
                     }
@@ -483,10 +639,175 @@ var FlinkApp = /** @class */ (function () {
             }
             else {
                 this.handlerRouteCache.set(methodAndRoute_1, JSON.stringify(routeProps));
-                FlinkLog_1.log.info("Registered route ".concat(methodAndRoute_1));
+                initLog.info("Registered ".concat(streamFormat ? "streaming " : "", "route ").concat(methodAndRoute_1).concat(streamFormat ? " (".concat(streamFormat, ")") : ""));
             }
         }
     };
+    /**
+     * 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)
+     */
+    FlinkApp.prototype.loadSchemaManifest = function () {
+        // Return cached manifest if already loaded
+        if (this.schemaManifest) {
+            return this.schemaManifest;
+        }
+        var fs = require("fs");
+        var path = require("path");
+        var manifestPath = path.join(process.cwd(), "dist/.flink/schema-manifest.json");
+        if (!fs.existsSync(manifestPath)) {
+            FlinkLog_1.log.warn("Schema manifest not found at dist/.flink/schema-manifest.json - handlers/tools may not have validation schemas");
+            var emptyManifest = { definitions: {}, handlers: {}, tools: {} };
+            this.schemaManifest = emptyManifest;
+            return emptyManifest;
+        }
+        try {
+            var manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+            // Check version for backward compatibility
+            if (manifest.version === "2.0") {
+                // New format with schema universe and AJV global registry
+                this.schemaManifest = manifest;
+                // Initialize AJV and register all schemas
+                this.schemaAjv = new ajv_1.default({
+                    strict: false, // Allow additional properties by default
+                    allErrors: true, // Return all validation errors, not just first
+                });
+                (0, ajv_formats_1.default)(this.schemaAjv);
+                // Register all schemas in the universe
+                var schemas = manifest.schemas || {};
+                for (var _i = 0, _a = Object.values(schemas); _i < _a.length; _i++) {
+                    var schema = _a[_i];
+                    if (schema && typeof schema === "object" && schema.$id) {
+                        // Skip schemas with unresolved generic type parameters (T, U, V, etc.)
+                        if (this.hasUnresolvedTypeParams(schema, Object.keys(schemas))) {
+                            FlinkLog_1.log.debug("Skipping registration of generic schema: ".concat(schema.$id));
+                            continue;
+                        }
+                        this.schemaAjv.addSchema(schema);
+                    }
+                }
+                FlinkLog_1.log.debug("Loaded schema manifest v2.0: ".concat(Object.keys(schemas).length, " schemas, ").concat(Object.keys(manifest.handlers).length, " handlers, ").concat(Object.keys(manifest.tools).length, " tools"));
+                return manifest;
+            }
+            else {
+                // Old format (v1.0) - still supported for migration
+                FlinkLog_1.log.debug("Loaded schema manifest v1.0: ".concat(Object.keys(manifest.definitions || {}).length, " definitions, ").concat(Object.keys(manifest.handlers).length, " handlers, ").concat(Object.keys(manifest.tools).length, " tools"));
+                this.schemaManifest = manifest;
+                return manifest;
+            }
+        }
+        catch (error) {
+            FlinkLog_1.log.error("Failed to parse schema manifest:", error);
+            var errorManifest = { definitions: {}, handlers: {}, tools: {} };
+            this.schemaManifest = errorManifest;
+            return errorManifest;
+        }
+    };
+    /**
+     * Get the AJV instance for validation (v2.0 manifests).
+     * Returns undefined for v1.0 manifests.
+     */
+    FlinkApp.prototype.getSchemaAjv = function () {
+        return this.schemaAjv;
+    };
+    /**
+     * 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)
+     */
+    FlinkApp.prototype.registerSchemas = function (pluginId, schemas) {
+        // Ensure schema manifest and AJV are initialized
+        this.loadSchemaManifest();
+        if (!this.schemaAjv) {
+            // If no v2.0 manifest exists, create a fresh AJV instance
+            this.schemaAjv = new ajv_1.default({
+                strict: false,
+                allErrors: true,
+            });
+            (0, ajv_formats_1.default)(this.schemaAjv);
+        }
+        for (var _i = 0, _a = Object.values(schemas); _i < _a.length; _i++) {
+            var schema = _a[_i];
+            if (schema && typeof schema === "object" && schema.$id) {
+                // Skip if already registered
+                if (this.schemaAjv.getSchema(schema.$id)) {
+                    continue;
+                }
+                try {
+                    this.schemaAjv.addSchema(schema);
+                }
+                catch (err) {
+                    FlinkLog_1.log.warn("Failed to register plugin schema ".concat(schema.$id, ": ").concat(err));
+                }
+            }
+        }
+        FlinkLog_1.log.debug("Registered ".concat(Object.keys(schemas).length, " schemas from plugin '").concat(pluginId, "'"));
+    };
+    /**
+     * 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
+     */
+    FlinkApp.prototype.hasUnresolvedTypeParams = function (schema, registeredSchemaIds) {
+        var schemaIdSet = new Set(registeredSchemaIds);
+        var checkRefs = function (obj) {
+            if (!obj || typeof obj !== "object") {
+                return false;
+            }
+            if (Array.isArray(obj)) {
+                return obj.some(function (item) { return checkRefs(item); });
+            }
+            for (var _i = 0, _a = Object.entries(obj); _i < _a.length; _i++) {
+                var _b = _a[_i], key = _b[0], value = _b[1];
+                if (key === "$ref" && typeof value === "string") {
+                    // Check if ref is a single uppercase letter (generic type param)
+                    // and not in the registered schema IDs
+                    if (/^[A-Z]$/.test(value) && !schemaIdSet.has(value)) {
+                        return true;
+                    }
+                }
+                else if (typeof value === "object") {
+                    if (checkRefs(value)) {
+                        return true;
+                    }
+                }
+            }
+            return false;
+        };
+        return checkRefs(schema);
+    };
+    /**
+     * 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
+     */
+    FlinkApp.prototype.resolveSchema = function (schemaName) {
+        if (!schemaName)
+            return undefined;
+        var manifest = this.loadSchemaManifest();
+        // v2.0 manifest - return schema from universe
+        if (manifest.version === "2.0" && manifest.schemas) {
+            return manifest.schemas[schemaName];
+        }
+        // v1.0 manifest - return from definitions
+        if (manifest.definitions) {
+            return manifest.definitions[schemaName];
+        }
+        return undefined;
+    };
     /**
      * Register handlers found within the `/src/handlers`
      * directory in Flink App.
@@ -495,47 +816,77 @@ var FlinkApp = /** @class */ (function () {
      */
     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;
+            var schemaManifest, schemaCount, _i, _a, _b, handler, assumedHttpMethod, __file, metadata, reqSchema, resSchema, pathParams, _c, _d, param;
+            var _e;
+            return __generator(this, function (_f) {
+                schemaManifest = this.loadSchemaManifest();
+                schemaCount = schemaManifest.version === "2.0" ? Object.keys(schemaManifest.schemas || {}).length : Object.keys(schemaManifest.definitions || {}).length;
+                FlinkLog_1.log.debug("Registering ".concat(schemaCount, " schemas with AJV (manifest version: ").concat(schemaManifest.version || "1.0", ")"));
+                for (_i = 0, _a = exports.autoRegisteredHandlers.sort(function (a, b) {
+                    var _a, _b, _c, _d, _e, _f;
+                    var orderDiff = (((_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);
+                    if (orderDiff !== 0)
+                        return orderDiff;
+                    // Static segments must be registered before parameterized ones to avoid
+                    // Express matching e.g. GET /jobs/by-tags with the /jobs/:id route.
+                    var aHasParam = ((_d = (_c = a.handler.Route) === null || _c === void 0 ? void 0 : _c.path) === null || _d === void 0 ? void 0 : _d.includes("/:")) ? 1 : 0;
+                    var bHasParam = ((_f = (_e = b.handler.Route) === null || _e === void 0 ? void 0 : _e.path) === null || _f === void 0 ? void 0 : _f.includes("/:")) ? 1 : 0;
+                    return aHasParam - bHasParam;
+                }); _i < _a.length; _i++) {
+                    _b = _a[_i], handler = _b.handler, assumedHttpMethod = _b.assumedHttpMethod, __file = _b.__file;
                     if (!handler.Route) {
-                        FlinkLog_1.log.error("Missing Props in handler ".concat(handler.__file));
+                        FlinkLog_1.log.error("Missing Props in handler ".concat(__file));
                         continue;
                     }
                     if (!handler.default) {
-                        FlinkLog_1.log.error("Missing exported handler function in handler ".concat(handler.__file));
+                        FlinkLog_1.log.error("Missing exported handler function in handler ".concat(__file));
                         continue;
                     }
-                    if (!!((_e = handler.__params) === null || _e === void 0 ? void 0 : _e.length)) {
+                    metadata = schemaManifest.handlers[__file || ""];
+                    reqSchema = handler.Route.reqSchema || this.resolveSchema(metadata === null || metadata === void 0 ? void 0 : metadata.reqSchemaName);
+                    resSchema = handler.Route.resSchema || this.resolveSchema(metadata === null || metadata === void 0 ? void 0 : metadata.resSchemaName);
+                    // Validation warnings
+                    if (!metadata &&
+                        (handler.Route.validation === FlinkHttpHandler_1.ValidationMode.Validate ||
+                            handler.Route.validation === FlinkHttpHandler_1.ValidationMode.ValidateRequest ||
+                            handler.Route.validation === FlinkHttpHandler_1.ValidationMode.ValidateResponse)) {
+                        FlinkLog_1.log.warn("Handler ".concat(__file, " expects validation but no metadata found in manifest"));
+                    }
+                    // Warn if schema name doesn't resolve
+                    if ((metadata === null || metadata === void 0 ? void 0 : metadata.reqSchemaName) && !reqSchema) {
+                        FlinkLog_1.log.warn("Handler ".concat(__file, " references reqSchema \"").concat(metadata.reqSchemaName, "\" but not found in schema universe"));
+                    }
+                    if ((metadata === null || metadata === void 0 ? void 0 : metadata.resSchemaName) && !resSchema) {
+                        FlinkLog_1.log.warn("Handler ".concat(__file, " references resSchema \"").concat(metadata.resSchemaName, "\" but not found in schema universe"));
+                    }
+                    if (!!((_e = metadata === null || metadata === void 0 ? void 0 : metadata.paramsMetadata) === 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++) {
+                        for (_c = 0, _d = metadata.paramsMetadata; _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, "'"));
+                                FlinkLog_1.log.error("Handler ".concat(__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"));
+                        if (pathParams.length !== metadata.paramsMetadata.length) {
+                            FlinkLog_1.log.warn("Handler ".concat(__file, " has ").concat(metadata.paramsMetadata.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 }),
+                        routeProps: __assign(__assign({}, handler.Route), { method: handler.Route.method || assumedHttpMethod || (metadata === null || metadata === void 0 ? void 0 : metadata.assumedMethod), 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,
+                            reqSchema: reqSchema,
+                            resSchema: resSchema,
                         },
-                        queryMetadata: handler.__query || [],
-                        paramsMetadata: handler.__params || [],
+                        queryMetadata: (metadata === null || metadata === void 0 ? void 0 : metadata.queryMetadata) || [],
+                        paramsMetadata: (metadata === null || metadata === void 0 ? void 0 : metadata.paramsMetadata) || [],
                     }, handler.default);
                 }
                 return [2 /*return*/];
             });
         });
     };
-    FlinkApp.prototype.registerAutoRegisterableJobs = function () {
+    FlinkApp.prototype.registerAutoRegisterableJobs = function (filter) {
         return __awaiter(this, void 0, void 0, function () {
             var _loop_1, this_1, _i, autoRegisteredJobs_1, _a, jobProps, jobFn, __file;
             var _this = this;
@@ -544,30 +895,33 @@ var FlinkApp = /** @class */ (function () {
                     throw new Error("Scheduler not initialized"); // should never happen
                 }
                 _loop_1 = function (jobProps, jobFn, __file) {
+                    if (filter && !filter(jobProps)) {
+                        return "continue";
+                    }
                     if (jobProps.cron && jobProps.interval) {
-                        FlinkLog_1.log.error("Cannot register job ".concat(jobProps.id, " - both cron and interval are set in ").concat(__file));
+                        schedulerLog.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));
+                        schedulerLog.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));
+                        schedulerLog.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));
+                        schedulerLog.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));
+                    schedulerLog.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"));
+                                    schedulerLog.debug("Job ".concat(jobProps.id, " completed"));
                                     if (jobProps.afterDelay) {
                                         // afterDelay runs only once, so we remove the job
                                         this.scheduler.removeById(jobProps.id);
@@ -576,7 +930,7 @@ var FlinkApp = /** @class */ (function () {
                             }
                         });
                     }); }, function (err) {
-                        FlinkLog_1.log.error("Job ".concat(jobProps.id, " threw unhandled exception ").concat(err));
+                        schedulerLog.error("Job ".concat(jobProps.id, " threw unhandled exception ").concat(err));
                         console.error(err);
                     });
                     if (jobProps.cron) {
@@ -597,17 +951,41 @@ var FlinkApp = /** @class */ (function () {
                         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);
+                        var delayMs = (0, ms_1.default)(jobProps.afterDelay);
+                        if (delayMs === 0) {
+                            setImmediate(function () { return __awaiter(_this, void 0, void 0, function () {
+                                var err_2;
+                                return __generator(this, function (_a) {
+                                    switch (_a.label) {
+                                        case 0:
+                                            _a.trys.push([0, 2, , 3]);
+                                            return [4 /*yield*/, jobFn({ ctx: this.ctx })];
+                                        case 1:
+                                            _a.sent();
+                                            return [3 /*break*/, 3];
+                                        case 2:
+                                            err_2 = _a.sent();
+                                            schedulerLog.error("Job ".concat(jobProps.id, " threw unhandled exception ").concat(err_2));
+                                            console.error(err_2);
+                                            return [3 /*break*/, 3];
+                                        case 3: return [2 /*return*/];
+                                    }
+                                });
+                            }); });
+                        }
+                        else {
+                            var job = new toad_scheduler_1.SimpleIntervalJob({
+                                milliseconds: delayMs,
+                                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));
+                        schedulerLog.error("Cannot register job ".concat(jobProps.id, " - no cron, interval or once set in ").concat(__file));
                         return "continue";
                     }
                 };
@@ -625,40 +1003,201 @@ var FlinkApp = /** @class */ (function () {
         // 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, schemaManifest, _i, autoRegisteredTools_1, toolFile, toolId, toolInstanceName, metadata, schemas, allSchemas, toolExecutor;
+            return __generator(this, function (_a) {
+                ToolExecutor = require("./ai/ToolExecutor").ToolExecutor;
+                getRepoInstanceName = require("./utils").getRepoInstanceName;
+                schemaManifest = this.loadSchemaManifest();
+                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);
+                    metadata = schemaManifest.tools[toolFile.__file || ""];
+                    schemas = metadata
+                        ? {
+                            inputSchema: this.resolveSchema(metadata.inputSchemaName),
+                            outputSchema: this.resolveSchema(metadata.outputSchemaName),
+                            inputTypeHint: metadata.inputTypeHint,
+                            outputTypeHint: metadata.outputTypeHint,
+                        }
+                        : undefined;
+                    // Warn if schema name doesn't resolve
+                    if ((metadata === null || metadata === void 0 ? void 0 : metadata.inputSchemaName) && !(schemas === null || schemas === void 0 ? void 0 : schemas.inputSchema)) {
+                        FlinkLog_1.log.warn("Tool ".concat(toolFile.__file, " references inputSchema \"").concat(metadata.inputSchemaName, "\" but not found in schema universe"));
+                    }
+                    if ((metadata === null || metadata === void 0 ? void 0 : metadata.outputSchemaName) && !(schemas === null || schemas === void 0 ? void 0 : schemas.outputSchema)) {
+                        FlinkLog_1.log.warn("Tool ".concat(toolFile.__file, " references outputSchema \"").concat(metadata.outputSchemaName, "\" but not found in schema universe"));
+                    }
+                    allSchemas = schemaManifest.version === "2.0" ? schemaManifest.schemas : schemaManifest.definitions;
+                    toolExecutor = new ToolExecutor(toolFile.Tool, toolFile.default, this.ctx, schemas, // Auto-generated schemas from manifest (resolved from definitions)
+                    allSchemas);
+                    this.tools[toolInstanceName] = toolExecutor;
+                    initLog.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;
+                    initLog.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)");
+            var _i, autoRegisteredRepos_1, _a, collectionName, repoInstanceName, Repo, repoInstance, pluginCtx, _b, autoRegisteredServices_1, _c, serviceInstanceName, Service, serviceInstance, _d, _e, repo, _f, _g, service, servicesWithInit;
+            return __generator(this, function (_h) {
+                switch (_h.label) {
+                    case 0:
+                        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;
+                                initLog.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;
+                        }, {});
+                        // Instantiate services (ctx not yet available - constructors must not access it)
+                        for (_b = 0, autoRegisteredServices_1 = exports.autoRegisteredServices; _b < autoRegisteredServices_1.length; _b++) {
+                            _c = autoRegisteredServices_1[_b], serviceInstanceName = _c.serviceInstanceName, Service = _c.Service;
+                            serviceInstance = new Service();
+                            this.services[serviceInstanceName] = serviceInstance;
+                            initLog.info("Registered service ".concat(serviceInstanceName));
+                        }
+                        this._ctx = {
+                            repos: this.repos,
+                            plugins: pluginCtx,
+                            auth: this.auth,
+                            agents: this.agents,
+                            services: this.services,
+                        };
+                        // Inject context into repos
+                        for (_d = 0, _e = Object.values(this.repos); _d < _e.length; _d++) {
+                            repo = _e[_d];
+                            repo.ctx = this.ctx;
+                        }
+                        // Inject context into services, then call onInit() in parallel
+                        for (_f = 0, _g = Object.values(this.services); _f < _g.length; _f++) {
+                            service = _g[_f];
+                            service.ctx = this.ctx;
+                        }
+                        servicesWithInit = Object.values(this.services).filter(function (s) { return typeof s.onInit === "function"; });
+                        if (!(servicesWithInit.length > 0)) return [3 /*break*/, 2];
+                        return [4 /*yield*/, Promise.all(servicesWithInit.map(function (s) { return s.onInit(); }))];
+                    case 1:
+                        _h.sent();
+                        _h.label = 2;
+                    case 2: return [2 /*return*/];
                 }
-                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,
-                };
-                for (_b = 0, _c = Object.values(this.repos); _b < _c.length; _b++) {
-                    repo = _c[_b];
-                    repo.ctx = this.ctx;
+            });
+        });
+    };
+    /**
+     * 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, this.agentObserver);
                 }
                 return [2 /*return*/];
             });
@@ -669,7 +1208,7 @@ var FlinkApp = /** @class */ (function () {
      */
     FlinkApp.prototype.initDb = function () {
         return __awaiter(this, void 0, void 0, function () {
-            var client, err_2;
+            var client, err_3;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
@@ -685,8 +1224,8 @@ var FlinkApp = /** @class */ (function () {
                         this.dbClient = client;
                         return [3 /*break*/, 4];
                     case 3:
-                        err_2 = _a.sent();
-                        FlinkLog_1.log.error("Failed to connect to db: " + err_2);
+                        err_3 = _a.sent();
+                        FlinkLog_1.log.error("Failed to connect to db: " + err_3);
                         process.exit(1);
                         return [3 /*break*/, 4];
                     case 4:
@@ -705,7 +1244,7 @@ var FlinkApp = /** @class */ (function () {
      */
     FlinkApp.prototype.initPluginDb = function (plugin) {
         return __awaiter(this, void 0, void 0, function () {
-            var client, err_3;
+            var client, err_4;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
@@ -726,14 +1265,14 @@ var FlinkApp = /** @class */ (function () {
                         _a.label = 2;
                     case 2:
                         _a.trys.push([2, 4, , 5]);
-                        FlinkLog_1.log.debug("Connecting to '".concat(plugin.id, "' db"));
+                        initLog.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);
+                        err_4 = _a.sent();
+                        FlinkLog_1.log.error("Failed to connect to db defined in plugin '".concat(plugin.id, "': ") + err_4);
                         return [3 /*break*/, 5];
                     case 5: return [2 /*return*/];
                 }
@@ -748,12 +1287,40 @@ var FlinkApp = /** @class */ (function () {
                         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)];
+                        return [4 /*yield*/, this.auth.authenticateRequest(req, permissions, this._ctx)];
                     case 1: return [2 /*return*/, _a.sent()];
                 }
             });
         });
     };
+    /**
+     * 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.
+     */
+    FlinkApp.prototype.invokeOnError = function (errorResponse, req, method, path) {
+        if (!this.onError) {
+            return;
+        }
+        try {
+            var result = this.onError(errorResponse, {
+                req: req,
+                method: method,
+                path: path,
+                reqId: req.reqId,
+                ctx: this.ctx,
+            });
+            // 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));
+        }
+    };
     FlinkApp.prototype.getRegisteredRoutes = function () {
         return Array.from(this.handlerRouteCache.values());
     };
@@ -765,19 +1332,91 @@ var FlinkApp = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    Object.defineProperty(FlinkApp.prototype, "leaderElectionConfig", {
+        get: function () {
+            var _a;
+            var opt = (_a = this.schedulingOptions) === null || _a === void 0 ? void 0 : _a.leaderElection;
+            if (!opt)
+                return undefined;
+            return opt === true ? {} : opt;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    FlinkApp.prototype.startLeaderElection = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var hasAllInstanceJobs, opts;
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!!this.db) return [3 /*break*/, 2];
+                        schedulerLog.warn("Leader election is enabled but no database is configured. " +
+                            "Leader election requires a MongoDB connection to coordinate between instances. " +
+                            "Either add a database connection via the `db` option, or remove `scheduling.leaderElection` from your config. " +
+                            "Jobs will run on ALL instances without leader election.");
+                        // Fall back to running jobs on all instances
+                        this.scheduler = new toad_scheduler_1.ToadScheduler();
+                        return [4 /*yield*/, this.registerAutoRegisterableJobs()];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                    case 2:
+                        hasAllInstanceJobs = exports.autoRegisteredJobs.some(function (j) { return j.Job.runOnAllInstances; });
+                        if (!hasAllInstanceJobs) return [3 /*break*/, 4];
+                        this.allInstanceScheduler = new toad_scheduler_1.ToadScheduler();
+                        this.scheduler = this.allInstanceScheduler;
+                        return [4 /*yield*/, this.registerAutoRegisterableJobs(function (job) { return !!job.runOnAllInstances; })];
+                    case 3:
+                        _a.sent();
+                        this.scheduler = undefined;
+                        _a.label = 4;
+                    case 4:
+                        opts = this.leaderElectionConfig;
+                        this.leaderElection = new LeaderElection_1.LeaderElection(this.db, opts);
+                        return [4 /*yield*/, this.leaderElection.start(
+                            // onBecameLeader
+                            function () { return __awaiter(_this, void 0, void 0, function () {
+                                return __generator(this, function (_a) {
+                                    switch (_a.label) {
+                                        case 0:
+                                            schedulerLog.info("This instance is now the leader - starting scheduled jobs");
+                                            this.scheduler = new toad_scheduler_1.ToadScheduler();
+                                            return [4 /*yield*/, this.registerAutoRegisterableJobs(function (job) { return !job.runOnAllInstances; })];
+                                        case 1:
+                                            _a.sent();
+                                            return [2 /*return*/];
+                                    }
+                                });
+                            }); }, 
+                            // onLostLeadership
+                            function () {
+                                schedulerLog.info("This instance lost leadership - stopping scheduled jobs");
+                                if (_this.scheduler) {
+                                    _this.scheduler.stop();
+                                    _this.scheduler = undefined;
+                                }
+                            })];
+                    case 5:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
     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));
+            initLog.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, ")"));
+        initLog.debug("Using modern MongoDB client options (driver version ".concat(driverVersion, ")"));
         return {
             serverApi: {
                 version: mongodb_1.ServerApiVersion.v1,