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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @flink-app/flink
 
+## 2.0.0-alpha.49
+
+### Patch Changes
+
+-   Typescript include fix
+
+## 2.0.0-alpha.48
+
+### Minor Changes
+
+-   AI features
+
 ## 1.0.0
 
 ### Minor Changes

package/cli/build.ts

@@ -40,7 +40,14 @@ module.exports = async function run(args: string[]) {
         process.exit(1);
     }
 
-    await Promise.all([compiler.parseRepos(), compiler.parseHandlers(exclude.split(",")), compiler.parseJobs(), compiler.generateStartScript()]);
+    await Promise.all([
+        compiler.parseRepos(),
+        compiler.parseHandlers(exclude.split(",")),
+        compiler.parseTools(),
+        compiler.parseAgents(),
+        compiler.parseJobs(),
+        compiler.generateStartScript(),
+    ]);
 
     console.log(`Compilation done, took ${Date.now() - startTime}ms`);
 

package/cli/run.ts

@@ -63,7 +63,14 @@ module.exports = async function run(args: string[]) {
         process.exit(1);
     }
 
-    await Promise.all([compiler.parseRepos(), compiler.parseHandlers(), compiler.parseJobs(), compiler.generateStartScript(entry)]);
+    await Promise.all([
+        compiler.parseRepos(),
+        compiler.parseHandlers(),
+        compiler.parseTools(),
+        compiler.parseAgents(),
+        compiler.parseJobs(),
+        compiler.generateStartScript(entry)
+    ]);
 
     console.log(`Compilation done, took ${Date.now() - startTime}ms`);
 

package/dist/cli/build.js

@@ -65,7 +65,14 @@ module.exports = function run(args) {
                     if (!compiler.getPreEmitDiagnostics()) {
                         process.exit(1);
                     }
-                    return [4 /*yield*/, Promise.all([compiler.parseRepos(), compiler.parseHandlers(exclude.split(",")), compiler.parseJobs(), compiler.generateStartScript()])];
+                    return [4 /*yield*/, Promise.all([
+                            compiler.parseRepos(),
+                            compiler.parseHandlers(exclude.split(",")),
+                            compiler.parseTools(),
+                            compiler.parseAgents(),
+                            compiler.parseJobs(),
+                            compiler.generateStartScript(),
+                        ])];
                 case 2:
                     _a.sent();
                     console.log("Compilation done, took ".concat(Date.now() - startTime, "ms"));

package/dist/cli/run.js

@@ -83,7 +83,14 @@ module.exports = function run(args) {
                     if (!compiler.getPreEmitDiagnostics()) {
                         process.exit(1);
                     }
-                    return [4 /*yield*/, Promise.all([compiler.parseRepos(), compiler.parseHandlers(), compiler.parseJobs(), compiler.generateStartScript(entry)])];
+                    return [4 /*yield*/, Promise.all([
+                            compiler.parseRepos(),
+                            compiler.parseHandlers(),
+                            compiler.parseTools(),
+                            compiler.parseAgents(),
+                            compiler.parseJobs(),
+                            compiler.generateStartScript(entry)
+                        ])];
                 case 2:
                     _a.sent();
                     console.log("Compilation done, took ".concat(Date.now() - startTime, "ms"));

package/dist/src/FlinkApp.d.ts

@@ -3,6 +3,9 @@ import express, { Express } from "express";
 import { JSONSchema7 } from "json-schema";
 import { Db, MongoClient } from "mongodb";
 import { ToadScheduler } from "toad-scheduler";
+import { FlinkAgentFile } from "./ai/FlinkAgent";
+import { FlinkToolFile } from "./ai/FlinkTool";
+import { LLMAdapter } from "./ai/LLMAdapter";
 import { FlinkAuthPlugin } from "./auth/FlinkAuthPlugin";
 import { FlinkContext } from "./FlinkContext";
 import { FlinkError } from "./FlinkErrors";
@@ -39,6 +42,16 @@ export declare const autoRegisteredRepos: {
  * are picked up by TypeScript compiler
  */
 export declare const autoRegisteredJobs: FlinkJobFile[];
+/**
+ * This will be populated at compile time when the apps tools
+ * are picked up by TypeScript compiler
+ */
+export declare const autoRegisteredTools: FlinkToolFile[];
+/**
+ * This will be populated at compile time when the apps agents
+ * are picked up by TypeScript compiler
+ */
+export declare const autoRegisteredAgents: FlinkAgentFile[];
 export interface FlinkOptions {
     /**
      * Name of application, will only show in logs and in HTTP header.
@@ -118,6 +131,16 @@ export interface FlinkOptions {
          */
         enabled?: boolean;
     };
+    /**
+     * AI configuration for agents and tools
+     * Register LLM adapters with custom IDs (e.g., "anthropic", "openai", "anthropic-eu", etc.)
+     * This allows multiple adapters of the same type with different configurations
+     */
+    ai?: {
+        llms?: {
+            [id: string]: LLMAdapter;
+        };
+    };
     /**
      * If true, the HTTP server will be disabled.
      * Only useful when starting a Flink app for testing purposes.
@@ -226,6 +249,9 @@ export declare class FlinkApp<C extends FlinkContext> {
     private expressServer;
     private onError?;
     private repos;
+    private llmAdapters;
+    private tools;
+    private agents;
     /**
      * Internal cache used to track registered handlers and potentially any overlapping routes
      */
@@ -253,11 +279,18 @@ export declare class FlinkApp<C extends FlinkContext> {
     private registerAutoRegisterableHandlers;
     private registerAutoRegisterableJobs;
     addRepo(instanceName: string, repoInstance: FlinkRepo<C, any>): void;
+    private registerAutoRegisterableTools;
+    private registerAutoRegisterableAgents;
     /**
      * Constructs the app context. Will inject context in all components
      * except for handlers which are handled in later stage.
      */
     private buildContext;
+    /**
+     * Initialize agents after they've been registered and context is ready
+     * Must be called after registerAutoRegisterableAgents()
+     */
+    private initializeAgents;
     /**
      * Connects to database.
      */

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.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"));
@@ -64,6 +64,7 @@ var uuid_1 = require("uuid");
 var FlinkErrors_1 = require("./FlinkErrors");
 var FlinkHttpHandler_1 = require("./FlinkHttpHandler");
 var FlinkLog_1 = require("./FlinkLog");
+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();
@@ -93,8 +94,19 @@ 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 = [];
 var FlinkApp = /** @class */ (function () {
     function FlinkApp(opts) {
+        var _a;
         this.handlers = [];
         this.started = false;
         this.debug = false;
@@ -102,6 +114,9 @@ var FlinkApp = /** @class */ (function () {
         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
          */
@@ -124,6 +139,11 @@ 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));
+        }
     }
     Object.defineProperty(FlinkApp.prototype, "ctx", {
         get: function () {
@@ -152,13 +172,42 @@ var FlinkApp = /** @class */ (function () {
                             offsetTime = Date.now();
                             FlinkLog_1.log.bgColorLog("cyan", "Init db took ".concat(offsetTime - startTime, " ms"));
                         }
+                        // Build initial context (without agents - they'll be added later)
                         return [4 /*yield*/, this.buildContext()];
                     case 2:
+                        // Build initial context (without agents - they'll be added later)
                         _e.sent();
                         if (this.debug) {
                             FlinkLog_1.log.bgColorLog("cyan", "Build context took ".concat(Date.now() - offsetTime, " ms"));
                             offsetTime = Date.now();
                         }
+                        // Register tools (needs context for ToolExecutor)
+                        return [4 /*yield*/, this.registerAutoRegisterableTools()];
+                    case 3:
+                        // Register tools (needs context for ToolExecutor)
+                        _e.sent();
+                        if (this.debug) {
+                            FlinkLog_1.log.bgColorLog("cyan", "Register tools took ".concat(Date.now() - offsetTime, " ms"));
+                            offsetTime = Date.now();
+                        }
+                        // Register agents (creates agent instances)
+                        return [4 /*yield*/, this.registerAutoRegisterableAgents()];
+                    case 4:
+                        // Register agents (creates agent instances)
+                        _e.sent();
+                        if (this.debug) {
+                            FlinkLog_1.log.bgColorLog("cyan", "Register agents took ".concat(Date.now() - offsetTime, " ms"));
+                            offsetTime = Date.now();
+                        }
+                        // Initialize agents now that context and tools are ready
+                        return [4 /*yield*/, this.initializeAgents()];
+                    case 5:
+                        // Initialize agents now that context and tools are ready
+                        _e.sent();
+                        if (this.debug) {
+                            FlinkLog_1.log.bgColorLog("cyan", "Initialize agents took ".concat(Date.now() - offsetTime, " ms"));
+                            offsetTime = Date.now();
+                        }
                         if (this.isSchedulingEnabled) {
                             this.scheduler = new toad_scheduler_1.ToadScheduler();
                         }
@@ -184,45 +233,45 @@ var FlinkApp = /** @class */ (function () {
                             });
                         }
                         _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:
+                    case 7:
                         db = _e.sent();
-                        _e.label = 5;
-                    case 5:
-                        if (!plugin.init) return [3 /*break*/, 7];
+                        _e.label = 8;
+                    case 8:
+                        if (!plugin.init) return [3 /*break*/, 10];
                         return [4 /*yield*/, plugin.init(this, db)];
-                    case 6:
+                    case 9:
                         _e.sent();
-                        _e.label = 7;
-                    case 7:
+                        _e.label = 10;
+                    case 10:
                         FlinkLog_1.log.info("Initialized plugin '".concat(plugin.id, "'"));
-                        _e.label = 8;
-                    case 8:
+                        _e.label = 11;
+                    case 11:
                         _b++;
-                        return [3 /*break*/, 3];
-                    case 9: return [4 /*yield*/, this.registerAutoRegisterableHandlers()];
-                    case 10:
+                        return [3 /*break*/, 6];
+                    case 12: return [4 /*yield*/, this.registerAutoRegisterableHandlers()];
+                    case 13:
                         _e.sent();
                         if (this.debug) {
                             FlinkLog_1.log.bgColorLog("cyan", "Register handlers took ".concat(Date.now() - offsetTime, " ms"));
                             offsetTime = Date.now();
                         }
-                        if (!this.isSchedulingEnabled) return [3 /*break*/, 12];
+                        if (!this.isSchedulingEnabled) return [3 /*break*/, 15];
                         return [4 /*yield*/, this.registerAutoRegisterableJobs()];
-                    case 11:
+                    case 14:
                         _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:
+                        _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 () {
@@ -325,7 +374,7 @@ var FlinkApp = /** @class */ (function () {
         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"));
         }
@@ -342,12 +391,12 @@ var FlinkApp = /** @class */ (function () {
             if (schema.reqSchema && validationMode !== FlinkHttpHandler_1.ValidationMode.SkipValidation && validationMode !== FlinkHttpHandler_1.ValidationMode.ValidateResponse) {
                 validateReq_1 = ajv.compile(schema.reqSchema);
             }
-            // Compile response schema if validation mode requires it
-            if (schema.resSchema && validationMode !== FlinkHttpHandler_1.ValidationMode.SkipValidation && validationMode !== FlinkHttpHandler_1.ValidationMode.ValidateRequest) {
+            // Skip response validation for streaming handlers (responses are stream chunks, not final JSON)
+            if (!streamFormat && 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, handlerRes, err_1, errorResponse, result, valid, formattedErrors;
+                var valid, formattedErrors, data, normalizedQuery, _i, _a, _b, key, value, stream, handlerRes, err_1, errorResponse, result, valid, formattedErrors;
                 return __generator(this, function (_c) {
                     switch (_c.label) {
                         case 0:
@@ -374,7 +423,8 @@ var FlinkApp = /** @class */ (function () {
                                         })];
                                 }
                             }
-                            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,6 +452,7 @@ var FlinkApp = /** @class */ (function () {
                                 }
                                 req.query = normalizedQuery;
                             }
+                            stream = streamFormat ? StreamWriterFactory_1.StreamWriterFactory.create(res, streamFormat) : undefined;
                             _c.label = 3;
                         case 3:
                             _c.trys.push([3, 5, , 6]);
@@ -409,6 +460,7 @@ var FlinkApp = /** @class */ (function () {
                                     req: req,
                                     ctx: this.ctx,
                                     origin: routeProps.origin,
+                                    stream: stream,
                                 })];
                         case 4:
                             // 👇 This is where the actual handler gets invoked
@@ -416,6 +468,16 @@ var FlinkApp = /** @class */ (function () {
                             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) {
@@ -456,6 +518,14 @@ var FlinkApp = /** @class */ (function () {
                             }
                             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) {
@@ -483,7 +553,7 @@ var FlinkApp = /** @class */ (function () {
             }
             else {
                 this.handlerRouteCache.set(methodAndRoute_1, JSON.stringify(routeProps));
-                FlinkLog_1.log.info("Registered route ".concat(methodAndRoute_1));
+                FlinkLog_1.log.info("Registered ".concat(streamFormat ? 'streaming ' : '', "route ").concat(methodAndRoute_1).concat(streamFormat ? " (".concat(streamFormat, ")") : ''));
             }
         }
     };
@@ -625,6 +695,137 @@ 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, _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);
+                    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, SubAgentExecutor, _loop_2, this_2, _i, autoRegisteredAgents_1, agentFile, _b, autoRegisteredAgents_2, agentFile, AgentClass, agentInstance, _c, _d, agentRef, subAgentInstanceName;
+            return __generator(this, function (_e) {
+                _a = require("./utils"), getRepoInstanceName = _a.getRepoInstanceName, toKebabCase = _a.toKebabCase;
+                SubAgentExecutor = require("./ai/SubAgentExecutor").SubAgentExecutor;
+                _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 || toKebabCase(AgentClass.name);
+                    // 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) {
+                        var existingId = agent.id || toKebabCase(agent.constructor.name);
+                        return existingId === agentId;
+                    });
+                    if (existingAgentWithSameId) {
+                        throw new Error("Duplicate agent ID: \"".concat(agentId, "\". ") +
+                            "Agent class \"".concat(AgentClass.name, "\" conflicts with existing agent \"").concat(existingAgentWithSameId.constructor.name, "\". ") +
+                            "Agent IDs are derived from class names using kebab-case (e.g., CarAgent \u2192 car-agent). " +
+                            "Use an explicit 'id' property to resolve this conflict:\n" +
+                            "  id = \"my-unique-id\";");
+                    }
+                    // Validate tools exist
+                    for (var _f = 0, _g = agentInstance.tools; _f < _g.length; _f++) {
+                        var toolRef = _g[_f];
+                        // Handle both string IDs and tool file references
+                        var toolId = typeof toolRef === "string"
+                            ? toolRef
+                            : toolRef.Tool.id; // Extract ID from FlinkToolFile
+                        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));
+                        }
+                    }
+                    // Validate and register sub-agents
+                    if (agentInstance.agents && agentInstance.agents.length > 0) {
+                        for (var _h = 0, _j = agentInstance.agents; _h < _j.length; _h++) {
+                            var agentRef = _j[_h];
+                            // Get instance name directly from class reference or string
+                            var subAgentInstanceName = typeof agentRef === "string" ? agentRef : getRepoInstanceName(agentRef.name);
+                            // Validate that sub-agent will exist (will be registered in this loop)
+                            // For now, just log - actual validation happens at runtime
+                            FlinkLog_1.log.debug("Agent ".concat(AgentClass.name, " references sub-agent ").concat(subAgentInstanceName));
+                            // Create a SubAgentExecutor as a special tool
+                            var subAgentToolName = "ask_".concat(subAgentInstanceName);
+                            var subAgentExecutor = new SubAgentExecutor(subAgentInstanceName, this_2.ctx);
+                            // Register as a tool so it appears in the agent's tool list
+                            this_2.tools[subAgentToolName] = subAgentExecutor;
+                            FlinkLog_1.log.debug("Created sub-agent tool ".concat(subAgentToolName, " for ").concat(subAgentInstanceName));
+                        }
+                    }
+                    // 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);
+                }
+                // Second pass: validate all sub-agent references
+                for (_b = 0, autoRegisteredAgents_2 = exports.autoRegisteredAgents; _b < autoRegisteredAgents_2.length; _b++) {
+                    agentFile = autoRegisteredAgents_2[_b];
+                    AgentClass = agentFile.default;
+                    if (!AgentClass) {
+                        continue;
+                    }
+                    agentInstance = new AgentClass();
+                    if (agentInstance.agents && agentInstance.agents.length > 0) {
+                        for (_c = 0, _d = agentInstance.agents; _c < _d.length; _c++) {
+                            agentRef = _d[_c];
+                            subAgentInstanceName = typeof agentRef === "string" ? agentRef : getRepoInstanceName(agentRef.name);
+                            if (!this.agents[subAgentInstanceName]) {
+                                FlinkLog_1.log.error("Agent ".concat(AgentClass.name, " references sub-agent ").concat(subAgentInstanceName, " which is not registered"));
+                                throw new Error("Invalid sub-agent reference in agent ".concat(AgentClass.name, ": ").concat(subAgentInstanceName));
+                            }
+                        }
+                    }
+                }
+                return [2 /*return*/];
+            });
+        });
+    };
     /**
      * Constructs the app context. Will inject context in all components
      * except for handlers which are handled in later stage.
@@ -655,6 +856,7 @@ var FlinkApp = /** @class */ (function () {
                     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];
@@ -664,6 +866,24 @@ var FlinkApp = /** @class */ (function () {
             });
         });
     };
+    /**
+     * 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.
      */

package/dist/src/FlinkContext.d.ts

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