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

package/dist/src/FlinkHttpHandler.d.ts

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

package/dist/src/TypeScriptCompiler.d.ts

@@ -18,6 +18,28 @@ declare class TypeScriptCompiler {
      */
     private tsSchemasSymbolsToImports;
     constructor(cwd: string);
+    /**
+     * Loads additional source paths from tsconfig.json's flink configuration.
+     * Allows projects to specify extra directories to include in compilation.
+     *
+     * Example tsconfig.json:
+     * {
+     *   "flink": {
+     *     "sourcePaths": ["src/custom-types/**\/*.ts", "src/utils/**\/*.ts"]
+     *   }
+     * }
+     */
+    private getFlinkSourcePaths;
+    /**
+     * Recursively resolves and adds imported files to the project.
+     * This ensures that files imported by handlers, schemas, etc. are available for type resolution.
+     *
+     * Handles three types of imports:
+     * 1. Relative imports (./foo, ../bar) - always resolved
+     * 2. Workspace package imports (@mycompany/shared) - resolved if symlinked outside node_modules
+     * 3. External packages (lodash, express) - skipped to avoid loading entire dependency trees
+     */
+    private resolveImportedFiles;
     /**
      * Detects if the project is using ESM (ECMAScript Modules)
      * by checking type in package.json.
@@ -41,6 +63,15 @@ declare class TypeScriptCompiler {
      * exists. Warnings will be passed thru but logged.
      */
     getPreEmitDiagnostics(): boolean;
+    /**
+     * Finds a variable declaration by its TypeScript type name.
+     * This allows finding variables based on their type annotation rather than variable name.
+     *
+     * @param sf Source file to search in
+     * @param typeName Name of the type to search for (e.g., "FlinkToolProps", "FlinkAgentProps")
+     * @returns The first matching variable declaration, or undefined if not found
+     */
+    private findVariableDeclarationByType;
     /**
      * Scans project for handlers and add those to Flink
      * "singleton" property `autoRegisteredHandlers` so they can
@@ -55,6 +86,17 @@ declare class TypeScriptCompiler {
      */
     private parseHandlerDir;
     parseRepos(): Promise<SourceFile>;
+    /**
+     * Scans project for tools and adds those to Flink
+     * "singleton" property `autoRegisteredTools` so they can
+     * be registered during start.
+     */
+    parseTools(): Promise<SourceFile>;
+    /**
+     * Scans project for agents and validates tool references.
+     * Agents are declarative (no default function).
+     */
+    parseAgents(): Promise<SourceFile>;
     /**
      * Generates a start script that will import references to handlers, repos and the
      * actual Flink app to start.

package/dist/src/TypeScriptCompiler.js

@@ -130,11 +130,100 @@ var TypeScriptCompiler = /** @class */ (function () {
         this.project = new ts_morph_1.Project({
             tsConfigFilePath: tsConfigPath,
             compilerOptions: compilerOptions,
+            skipAddingFilesFromTsConfig: true, // Don't auto-load all files - we'll add specific directories we need
         });
+        // Load Flink-specific source paths from tsconfig.json if available
+        var additionalSourcePaths = this.getFlinkSourcePaths(tsConfigPath);
+        // Only add source files from directories we actually need to process
+        // This prevents loading all files from tsconfig include patterns and reduces memory usage
+        var defaultSourcePaths = [
+            (0, path_1.join)(cwd, "src/handlers/**/*.ts"),
+            (0, path_1.join)(cwd, "src/repos/**/*.ts"),
+            (0, path_1.join)(cwd, "src/tools/**/*.ts"),
+            (0, path_1.join)(cwd, "src/agents/**/*.ts"),
+            (0, path_1.join)(cwd, "src/jobs/**/*.ts"),
+            (0, path_1.join)(cwd, "src/index.ts"),
+            (0, path_1.join)(cwd, "src/schemas/**/*.ts"), // Include schemas for type resolution
+        ];
+        var allSourcePaths = __spreadArray(__spreadArray([], defaultSourcePaths, true), additionalSourcePaths, true);
+        this.project.addSourceFilesAtPaths(allSourcePaths);
+        // Resolve imports: add any files imported by our source files
+        // This ensures schemas that import types from other locations work correctly
+        this.resolveImportedFiles();
         console.log("Loaded", this.project.getSourceFiles().length, "source file(s) from", cwd);
         console.log("Module system:", this.isEsm ? "ESM" : "CommonJS");
         console.log("Using module:", compilerOptions.module === ts_morph_1.ts.ModuleKind.ESNext ? "ESNext" : "CommonJS");
     }
+    /**
+     * Loads additional source paths from tsconfig.json's flink configuration.
+     * Allows projects to specify extra directories to include in compilation.
+     *
+     * Example tsconfig.json:
+     * {
+     *   "flink": {
+     *     "sourcePaths": ["src/custom-types/**\/*.ts", "src/utils/**\/*.ts"]
+     *   }
+     * }
+     */
+    TypeScriptCompiler.prototype.getFlinkSourcePaths = function (tsConfigPath) {
+        var _this = this;
+        try {
+            if (fs_1.default.existsSync(tsConfigPath)) {
+                var tsConfigContent = fs_1.default.readFileSync(tsConfigPath, "utf8");
+                var tsConfig = JSON.parse(tsConfigContent);
+                if (tsConfig.flink && Array.isArray(tsConfig.flink.sourcePaths)) {
+                    console.log("Found Flink-specific source paths:", tsConfig.flink.sourcePaths);
+                    return tsConfig.flink.sourcePaths.map(function (path) { return (0, path_1.join)(_this.cwd, path); });
+                }
+            }
+        }
+        catch (error) {
+            console.warn("Error reading Flink source paths from tsconfig.json:", error);
+        }
+        return [];
+    };
+    /**
+     * Recursively resolves and adds imported files to the project.
+     * This ensures that files imported by handlers, schemas, etc. are available for type resolution.
+     *
+     * Handles three types of imports:
+     * 1. Relative imports (./foo, ../bar) - always resolved
+     * 2. Workspace package imports (@mycompany/shared) - resolved if symlinked outside node_modules
+     * 3. External packages (lodash, express) - skipped to avoid loading entire dependency trees
+     */
+    TypeScriptCompiler.prototype.resolveImportedFiles = function () {
+        var processedFiles = new Set();
+        var filesToProcess = __spreadArray([], this.project.getSourceFiles(), true);
+        while (filesToProcess.length > 0) {
+            var sourceFile = filesToProcess.pop();
+            var filePath = sourceFile.getFilePath();
+            if (processedFiles.has(filePath)) {
+                continue;
+            }
+            processedFiles.add(filePath);
+            // Get all import declarations
+            var importDeclarations = sourceFile.getImportDeclarations();
+            for (var _i = 0, importDeclarations_1 = importDeclarations; _i < importDeclarations_1.length; _i++) {
+                var importDecl = importDeclarations_1[_i];
+                var moduleSpecifier = importDecl.getModuleSpecifierValue();
+                // Try to resolve the imported file
+                var moduleSourceFile = importDecl.getModuleSpecifierSourceFile();
+                if (moduleSourceFile) {
+                    var importedPath = moduleSourceFile.getFilePath();
+                    // For relative imports (./foo, ../bar), always include
+                    var isRelativeImport = moduleSpecifier.startsWith(".") || moduleSpecifier.startsWith("/");
+                    // For package imports (@foo/bar, foo), check if resolved path is outside node_modules
+                    // This handles workspace packages that are symlinked (pnpm, yarn workspaces)
+                    var isWorkspacePackage = !isRelativeImport && !importedPath.includes("node_modules");
+                    // Skip if it's in node_modules (external package) or already processed
+                    if ((isRelativeImport || isWorkspacePackage) && !processedFiles.has(importedPath)) {
+                        filesToProcess.push(moduleSourceFile);
+                    }
+                }
+            }
+        }
+        console.log("Resolved imports, total files loaded:", processedFiles.size);
+    };
     /**
      * Detects if the project is using ESM (ECMAScript Modules)
      * by checking type in package.json.
@@ -244,6 +333,48 @@ var TypeScriptCompiler = /** @class */ (function () {
         }
         return true;
     };
+    /**
+     * Finds a variable declaration by its TypeScript type name.
+     * This allows finding variables based on their type annotation rather than variable name.
+     *
+     * @param sf Source file to search in
+     * @param typeName Name of the type to search for (e.g., "FlinkToolProps", "FlinkAgentProps")
+     * @returns The first matching variable declaration, or undefined if not found
+     */
+    TypeScriptCompiler.prototype.findVariableDeclarationByType = function (sf, typeName) {
+        var _a;
+        // Get all variable declarations from the source file
+        var variableDeclarations = sf.getVariableDeclarations();
+        for (var _i = 0, variableDeclarations_1 = variableDeclarations; _i < variableDeclarations_1.length; _i++) {
+            var varDecl = variableDeclarations_1[_i];
+            // Check if the variable is exported
+            var variableStatement = varDecl.getVariableStatement();
+            if (!(variableStatement === null || variableStatement === void 0 ? void 0 : variableStatement.isExported())) {
+                continue;
+            }
+            // Check if it's a const declaration
+            if (((_a = varDecl.getVariableStatement()) === null || _a === void 0 ? void 0 : _a.getDeclarationKind()) !== ts_morph_1.VariableDeclarationKind.Const) {
+                continue;
+            }
+            // Get the type node (explicit type annotation)
+            var typeNode = varDecl.getTypeNode();
+            if (!typeNode) {
+                continue;
+            }
+            // Check if it's a type reference
+            if (typeNode.getKind() === ts_morph_1.SyntaxKind.TypeReference) {
+                var typeRef = typeNode;
+                var typeRefName = typeRef.getTypeName();
+                // Handle both simple type references (FlinkToolProps) and qualified names (flink.FlinkToolProps)
+                var typeRefText = typeRefName.getText();
+                // Check if the type name matches (either exact match or ends with the type name for qualified references)
+                if (typeRefText === typeName || typeRefText.endsWith(".".concat(typeName))) {
+                    return varDecl;
+                }
+            }
+        }
+        return undefined;
+    };
     /**
      * Scans project for handlers and add those to Flink
      * "singleton" property `autoRegisteredHandlers` so they can
@@ -408,6 +539,217 @@ var TypeScriptCompiler = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Scans project for tools and adds those to Flink
+     * "singleton" property `autoRegisteredTools` so they can
+     * be registered during start.
+     */
+    TypeScriptCompiler.prototype.parseTools = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var generatedFile, toolsArr, imports, i, _i, _a, sf, namespaceImport, toolPropsVar, toolPropsExportName, existingFile;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        generatedFile = this.createSourceFile(["generatedTools.ts"], "// Generated ".concat(new Date(), "\nimport { autoRegisteredTools } from \"@flink-app/flink\";\nexport const tools = [];\nautoRegisteredTools.push(...tools);\n    "));
+                        toolsArr = generatedFile.getVariableDeclarationOrThrow("tools").getFirstDescendantByKindOrThrow(ts_morph_1.SyntaxKind.ArrayLiteralExpression);
+                        imports = [];
+                        i = 0;
+                        for (_i = 0, _a = this.project.getSourceFiles(); _i < _a.length; _i++) {
+                            sf = _a[_i];
+                            if (!sf.getFilePath().includes("src/tools/")) {
+                                continue;
+                            }
+                            console.log("Detected tool ".concat(sf.getBaseName()));
+                            namespaceImport = sf.getBaseNameWithoutExtension().replace(/\./g, "_") + "_" + i;
+                            imports.push({
+                                defaultImport: "* as " + namespaceImport,
+                                moduleSpecifier: this.getModuleSpecifier(generatedFile, sf),
+                            });
+                            toolPropsVar = this.findVariableDeclarationByType(sf, "FlinkToolProps");
+                            toolPropsExportName = (toolPropsVar === null || toolPropsVar === void 0 ? void 0 : toolPropsVar.getName()) || "Tool";
+                            existingFile = sf.getVariableStatements().filter(function (vs) {
+                                var varNames = vs.getDeclarations().map(function (d) { return d.getName(); });
+                                return varNames.includes("__file");
+                            });
+                            existingFile.forEach(function (v) { return v.remove(); });
+                            // Append metadata to source file
+                            sf.addVariableStatement({
+                                declarationKind: ts_morph_1.VariableDeclarationKind.Const,
+                                isExported: true,
+                                declarations: [
+                                    {
+                                        name: "__file",
+                                        initializer: "\"".concat(sf.getBaseName(), "\""),
+                                    },
+                                ],
+                            });
+                            // Create an object that wraps the namespace and provides named access to the tool props
+                            toolsArr.insertElement(i, "{...".concat(namespaceImport, ", Tool: ").concat(namespaceImport, ".").concat(toolPropsExportName, "}"));
+                            i++;
+                        }
+                        generatedFile.addImportDeclarations(imports);
+                        return [4 /*yield*/, generatedFile.save()];
+                    case 1:
+                        _b.sent();
+                        return [2 /*return*/, generatedFile];
+                }
+            });
+        });
+    };
+    /**
+     * Scans project for agents and validates tool references.
+     * Agents are declarative (no default function).
+     */
+    TypeScriptCompiler.prototype.parseAgents = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var generatedFile, agentsArr, imports, registeredToolIds, _i, _a, sf, toolExport, props, idProp, idValue, i, _b, _c, sf, agentClass, toolsProperty, initializer, toolsArray, toolElements, _loop_1, _d, toolElements_1, toolElement, className, existingFile;
+            var _e;
+            return __generator(this, function (_f) {
+                switch (_f.label) {
+                    case 0:
+                        generatedFile = this.createSourceFile(["generatedAgents.ts"], "// Generated ".concat(new Date(), "\nimport { autoRegisteredAgents } from \"@flink-app/flink\";\nexport const agents = [];\nautoRegisteredAgents.push(...agents);\n    "));
+                        agentsArr = generatedFile.getVariableDeclarationOrThrow("agents").getFirstDescendantByKindOrThrow(ts_morph_1.SyntaxKind.ArrayLiteralExpression);
+                        imports = [];
+                        registeredToolIds = new Set();
+                        for (_i = 0, _a = this.project.getSourceFiles(); _i < _a.length; _i++) {
+                            sf = _a[_i];
+                            if (sf.getFilePath().includes("src/tools/")) {
+                                toolExport = this.findVariableDeclarationByType(sf, "FlinkToolProps");
+                                if (toolExport) {
+                                    props = toolExport.getFirstDescendantByKind(ts_morph_1.SyntaxKind.ObjectLiteralExpression);
+                                    idProp = (props === null || props === void 0 ? void 0 : props.getProperty("id")) || (props === null || props === void 0 ? void 0 : props.getProperty("name"));
+                                    if (idProp) {
+                                        idValue = idProp.getLastChildByKind(ts_morph_1.SyntaxKind.StringLiteral);
+                                        if (idValue) {
+                                            registeredToolIds.add(idValue.getLiteralText());
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                        i = 0;
+                        for (_b = 0, _c = this.project.getSourceFiles(); _b < _c.length; _b++) {
+                            sf = _c[_b];
+                            if (!sf.getFilePath().includes("src/agents/")) {
+                                continue;
+                            }
+                            agentClass = sf.getClasses().find(function (cls) {
+                                var baseClass = cls.getBaseClass();
+                                return (baseClass === null || baseClass === void 0 ? void 0 : baseClass.getName()) === "FlinkAgent";
+                            });
+                            if (!agentClass) {
+                                // Skip files without FlinkAgent class
+                                continue;
+                            }
+                            console.log("Detected agent ".concat(sf.getBaseName()));
+                            toolsProperty = agentClass.getProperty("tools");
+                            if (toolsProperty) {
+                                initializer = toolsProperty.getInitializer();
+                                if (initializer && initializer.getKind() === ts_morph_1.SyntaxKind.ArrayLiteralExpression) {
+                                    toolsArray = initializer;
+                                    toolElements = toolsArray.getElements();
+                                    _loop_1 = function (toolElement) {
+                                        var toolName = void 0;
+                                        // Handle string literals, method calls, and identifier references (tool imports)
+                                        if (toolElement.getKind() === ts_morph_1.SyntaxKind.StringLiteral) {
+                                            // Direct string: "tool-name"
+                                            toolName = toolElement.getText().replace(/['"]/g, "");
+                                        }
+                                        else if (toolElement.getKind() === ts_morph_1.SyntaxKind.CallExpression) {
+                                            // Method call: this.useTool("tool-name")
+                                            var args = toolElement.getArguments();
+                                            if (args.length > 0 && args[0].getKind() === ts_morph_1.SyntaxKind.StringLiteral) {
+                                                toolName = args[0].getText().replace(/['"]/g, "");
+                                            }
+                                            else {
+                                                console.warn("Agent ".concat(sf.getBaseName(), " has non-string tool reference, skipping validation"));
+                                                return "continue";
+                                            }
+                                        }
+                                        else if (toolElement.getKind() === ts_morph_1.SyntaxKind.Identifier) {
+                                            // Tool file reference (imported): SearchCarsByBrandTool
+                                            // Look up the import to find the actual tool file
+                                            var importName_1 = toolElement.getText();
+                                            var importDecl = sf.getImportDeclarations().find(function (imp) {
+                                                var namedImports = imp.getNamedImports();
+                                                return namedImports.some(function (ni) { return ni.getName() === importName_1; });
+                                            });
+                                            if (!importDecl) {
+                                                // Try namespace import (* as Foo)
+                                                var namespaceImport = sf.getImportDeclarations().find(function (imp) {
+                                                    var _a;
+                                                    return ((_a = imp.getNamespaceImport()) === null || _a === void 0 ? void 0 : _a.getText()) === importName_1;
+                                                });
+                                                if (namespaceImport) {
+                                                    var moduleSpecifier = namespaceImport.getModuleSpecifierValue();
+                                                    // Extract tool ID from the tool file path
+                                                    // e.g., "../tools/SearchCarsByBrandTool" -> find in registeredToolIds
+                                                    var toolFileName = (_e = moduleSpecifier.split("/").pop()) === null || _e === void 0 ? void 0 : _e.replace(/\.ts$/, "");
+                                                    var matchingTool = Array.from(registeredToolIds).find(function (id) {
+                                                        // Try to match by searching for the tool ID
+                                                        // This is a heuristic - we'll validate it exists
+                                                        return true; // Skip validation for imported tools for now
+                                                    });
+                                                    return "continue";
+                                                }
+                                                console.warn("Agent ".concat(sf.getBaseName(), " references tool \"").concat(importName_1, "\" but it's not imported, skipping validation"));
+                                                return "continue";
+                                            }
+                                            return "continue";
+                                        }
+                                        else {
+                                            console.warn("Agent ".concat(sf.getBaseName(), " has unexpected tool reference format: ").concat(toolElement.getText()));
+                                            return "continue";
+                                        }
+                                        if (!registeredToolIds.has(toolName)) {
+                                            console.error("Agent ".concat(sf.getBaseName(), " references tool \"").concat(toolName, "\" which does not exist"));
+                                            throw new Error("Invalid tool reference in agent ".concat(sf.getBaseName()));
+                                        }
+                                    };
+                                    for (_d = 0, toolElements_1 = toolElements; _d < toolElements_1.length; _d++) {
+                                        toolElement = toolElements_1[_d];
+                                        _loop_1(toolElement);
+                                    }
+                                }
+                            }
+                            className = agentClass.getName();
+                            if (!className) {
+                                console.error("Agent class in ".concat(sf.getBaseName(), " has no name"));
+                                continue;
+                            }
+                            imports.push({
+                                defaultImport: className,
+                                moduleSpecifier: this.getModuleSpecifier(generatedFile, sf),
+                            });
+                            existingFile = sf.getVariableStatements().filter(function (vs) {
+                                var varNames = vs.getDeclarations().map(function (d) { return d.getName(); });
+                                return varNames.includes("__file");
+                            });
+                            existingFile.forEach(function (v) { return v.remove(); });
+                            // Append metadata
+                            sf.addVariableStatement({
+                                declarationKind: ts_morph_1.VariableDeclarationKind.Const,
+                                isExported: true,
+                                declarations: [
+                                    {
+                                        name: "__file",
+                                        initializer: "\"".concat(sf.getBaseName(), "\""),
+                                    },
+                                ],
+                            });
+                            // Register the agent class
+                            agentsArr.insertElement(i, "{ default: ".concat(className, ", __file: \"").concat(sf.getBaseName(), "\" }"));
+                            i++;
+                        }
+                        generatedFile.addImportDeclarations(imports);
+                        return [4 /*yield*/, generatedFile.save()];
+                    case 1:
+                        _f.sent();
+                        return [2 /*return*/, generatedFile];
+                }
+            });
+        });
+    };
     /**
      * Generates a start script that will import references to handlers, repos and the
      * actual Flink app to start.
@@ -426,7 +768,7 @@ var TypeScriptCompiler = /** @class */ (function () {
                             console.error("Cannot find entry script '".concat(appEntryScript, "'"));
                             return [2 /*return*/, process.exit(1)];
                         }
-                        sf = this.createSourceFile(["start.ts"], "// Generated ".concat(new Date(), "\nimport \"./generatedHandlers").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedRepos").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedJobs").concat(this.isEsm ? ".js" : "", "\";\nimport \"..").concat(appEntryScript.replace(/\.ts/g, "")).concat(this.isEsm ? ".js" : "", "\";\nexport default {}; // Export an empty object to make it a module\n"));
+                        sf = this.createSourceFile(["start.ts"], "// Generated ".concat(new Date(), "\nimport \"./generatedHandlers").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedRepos").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedTools").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedAgents").concat(this.isEsm ? ".js" : "", "\";\nimport \"./generatedJobs").concat(this.isEsm ? ".js" : "", "\";\nimport \"..").concat(appEntryScript.replace(/\.ts/g, "")).concat(this.isEsm ? ".js" : "", "\";\nexport default {}; // Export an empty object to make it a module\n"));
                         return [4 /*yield*/, sf.save()];
                     case 1:
                         _a.sent();
@@ -528,7 +870,7 @@ var TypeScriptCompiler = /** @class */ (function () {
                     return [2 /*return*/]; // 'any' indicates that no schema is used
                 }
                 schemaText = schema.getText();
-                if (schemaText === 'void' || schemaText === 'undefined') {
+                if (schemaText === "void" || schemaText === "undefined") {
                     return [2 /*return*/];
                 }
                 handlerFileName = handlerFile.getBaseNameWithoutExtension().replace(/\./g, "_");
@@ -564,7 +906,7 @@ var TypeScriptCompiler = /** @class */ (function () {
                                 if (interfaceNameMatches) {
                                     for (_d = 0, interfaceNameMatches_1 = interfaceNameMatches; _d < interfaceNameMatches_1.length; _d++) {
                                         match = interfaceNameMatches_1[_d];
-                                        referencedInterfaceName = match.replace(/\s*\[$/, '').trim();
+                                        referencedInterfaceName = match.replace(/\s*\[$/, "").trim();
                                         referencedInterfaceDecl = handlerFile.getInterface(referencedInterfaceName) || handlerFile.getTypeAlias(referencedInterfaceName);
                                         if (referencedInterfaceDecl) {
                                             // Interface is in same file - copy it and all its dependencies recursively
@@ -663,7 +1005,7 @@ var TypeScriptCompiler = /** @class */ (function () {
                         if (interfaceNameMatches) {
                             for (_j = 0, interfaceNameMatches_2 = interfaceNameMatches; _j < interfaceNameMatches_2.length; _j++) {
                                 match = interfaceNameMatches_2[_j];
-                                interfaceName = match.replace(/\s*\[$/, '').trim();
+                                interfaceName = match.replace(/\s*\[$/, "").trim();
                                 interfaceDecl = handlerFile.getInterface(interfaceName) || handlerFile.getTypeAlias(interfaceName);
                                 if (interfaceDecl) {
                                     // Interface is in same file - copy it and all its dependencies recursively

package/dist/src/TypeScriptUtils.js

@@ -191,6 +191,10 @@ function getTypeMetadata(type) {
     if (!type || ["void", "any"].includes(type.getText())) {
         return [];
     }
+    // Handle empty object literal {} (used in streaming handlers)
+    if (type.getText() === "{}") {
+        return [];
+    }
     var symbol = getSymbolOrAlias(type);
     if (!symbol) {
         throw new Error("Could not get type symbol for type: " + type.getText());

package/dist/src/ai/AgentRunner.d.ts

@@ -0,0 +1,39 @@
+import { FlinkAgentProps, AgentExecuteInput, StreamChunk } from "./FlinkAgent";
+import { ToolExecutor } from "./ToolExecutor";
+import { LLMAdapter } from "./LLMAdapter";
+export declare class AgentRunner {
+    private agentProps;
+    private tools;
+    private agentName?;
+    private llmAdapter;
+    private maxTokens;
+    private temperature;
+    private maxSteps;
+    private timeoutMs;
+    private maxSubAgentDepth;
+    constructor(agentProps: FlinkAgentProps, tools: Map<string, ToolExecutor<any>>, llmAdapters: Map<string, LLMAdapter>, agentName?: string | undefined);
+    /**
+     * Phase 1: Stream generator that yields complete event on finish
+     * Phase 2: Will yield text_delta and tool events during execution
+     */
+    streamGenerator(input: AgentExecuteInput): AsyncGenerator<StreamChunk>;
+    /**
+     * Convert Message[] to LLM message format
+     * Supports multi-turn conversations with history
+     */
+    private convertMessages;
+    private getToolSchemas;
+    /**
+     * Filter tools based on user permissions
+     * Only returns schemas for tools the user has permission to use
+     *
+     * @param user - User object
+     * @param userPermissions - Optional resolved permissions from auth plugin (preferred)
+     */
+    private filterToolsByPermissions;
+    /**
+     * Build delegation chain from metadata for error messages
+     * Extracts parent agent IDs to show the full call stack
+     */
+    private buildDelegationChain;
+}