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

package/dist/src/ai/agentInstructions.js

@@ -0,0 +1,286 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentInstructions = agentInstructions;
+var fs = __importStar(require("fs"));
+var path = __importStar(require("path"));
+var handlebars_1 = __importDefault(require("handlebars"));
+/**
+ * In-memory file cache (per-process, not persistent)
+ */
+var fileCache = new Map();
+/**
+ * Get caller's file location using stack trace API
+ * This enables agent-relative path resolution for ./ and ../ prefixes
+ *
+ * Walks the stack to find the first frame outside this file,
+ * which is the agent class that called agentInstructions().
+ */
+function getCallerFilePath() {
+    var _a, _b;
+    var originalPrepareStackTrace = Error.prepareStackTrace;
+    Error.prepareStackTrace = function (_, stack) { return stack; };
+    var stack = new Error().stack;
+    Error.prepareStackTrace = originalPrepareStackTrace;
+    // Find first frame outside this file (skips getCallerFilePath, resolveFilePath, agentInstructions)
+    var thisFile = (_a = stack[0]) === null || _a === void 0 ? void 0 : _a.getFileName();
+    for (var i = 1; i < stack.length; i++) {
+        var fileName = (_b = stack[i]) === null || _b === void 0 ? void 0 : _b.getFileName();
+        if (fileName && fileName !== thisFile) {
+            return fileName;
+        }
+    }
+    throw new Error("Could not determine caller file location for agent-relative path");
+}
+/**
+ * Resolve file path based on prefix:
+ * - ./ or ../ = agent-relative (using caller's location)
+ * - otherwise = project root-relative
+ */
+function resolveFilePath(filePath) {
+    // Always try project root-relative first (most intuitive for users)
+    var cwdResolved = path.join(process.cwd(), filePath);
+    if (fs.existsSync(cwdResolved)) {
+        return cwdResolved;
+    }
+    if (filePath.startsWith("./") || filePath.startsWith("../")) {
+        // Agent-relative: get caller's file location via stack trace
+        var callerFile = getCallerFilePath();
+        var resolved = path.resolve(path.dirname(callerFile), filePath);
+        if (fs.existsSync(resolved)) {
+            return resolved;
+        }
+        // At runtime, callerFile points to compiled JS in dist/.
+        // Non-JS assets (e.g. .md instruction files) live in the source tree,
+        // so try the equivalent source path with dist/ removed.
+        var distIndex = resolved.lastIndexOf(path.sep + "dist" + path.sep);
+        if (distIndex !== -1) {
+            var sourcePath = resolved.substring(0, distIndex) + resolved.substring(distIndex + 5); // remove "/dist"
+            if (fs.existsSync(sourcePath)) {
+                return sourcePath;
+            }
+        }
+        return resolved;
+    }
+    else {
+        // Project root-relative
+        return cwdResolved;
+    }
+}
+/**
+ * Load file contents with smart caching
+ * Cache is invalidated when file modification time changes
+ */
+function loadFile(resolvedPath, originalPath) {
+    try {
+        var stats = fs.statSync(resolvedPath);
+        var mtime = stats.mtimeMs;
+        // Check cache
+        var cached = fileCache.get(resolvedPath);
+        if (cached && cached.mtime === mtime) {
+            return cached;
+        }
+        // Read file and update cache (clear compiled template on file change)
+        var content = fs.readFileSync(resolvedPath, "utf-8");
+        var entry = { content: content, mtime: mtime };
+        fileCache.set(resolvedPath, entry);
+        return entry;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new Error("Agent instructions file not found: ".concat(resolvedPath, " (from: ").concat(originalPath, ")"));
+        }
+        throw new Error("Failed to load agent instructions file: ".concat(resolvedPath, " - ").concat(err.message));
+    }
+}
+/**
+ * Render template using Handlebars with compiled template caching.
+ * Skips Handlebars entirely when content has no template expressions.
+ */
+function renderTemplate(cached, data, filePath) {
+    if (cached.hasTemplateExpressions === false) {
+        return cached.content;
+    }
+    try {
+        if (!cached.compiledTemplate) {
+            cached.hasTemplateExpressions = /\{\{/.test(cached.content);
+            if (!cached.hasTemplateExpressions) {
+                return cached.content;
+            }
+            cached.compiledTemplate = handlebars_1.default.compile(cached.content);
+        }
+        return cached.compiledTemplate(data);
+    }
+    catch (err) {
+        throw new Error("Failed to render template in ".concat(filePath, ": ").concat(err.message));
+    }
+}
+/**
+ * Load agent instructions from external files with template variable support
+ *
+ * Supports multiple file types: .md, .yaml, .txt, etc. (loaded as plain text)
+ *
+ * ## Path Resolution
+ *
+ * - `./` or `../` prefix: Agent-relative path (based on caller's file location)
+ * - Otherwise: Project root-relative path
+ *
+ * ## Template Variables
+ *
+ * Uses Handlebars templating with automatic context helpers:
+ * - `ctx`: Full FlinkContext
+ * - `agentContext`: AgentExecuteContext
+ * - `user`: Shortcut to agentContext.user
+ * - Custom variables from static object or callback
+ *
+ * ## Caching
+ *
+ * Files are cached in-memory and reloaded only when modification time changes
+ *
+ * @example Agent-relative path with static variables
+ * ```typescript
+ * export default class CarAgent extends FlinkAgent<AppCtx> {
+ *   id = "car-agent";
+ *   instructions = agentInstructions("./instructions/car-agent.md");
+ *   tools = [SearchCarsTool];
+ * }
+ * ```
+ *
+ * @example Dynamic variables with callback
+ * ```typescript
+ * export default class SupportAgent extends FlinkAgent<AppCtx> {
+ *   id = "support-agent";
+ *   instructions = agentInstructions(
+ *     "./instructions/support-agent.md",
+ *     (ctx, agentContext) => ({
+ *       isBusinessHours: new Date().getHours() >= 9 && new Date().getHours() < 17,
+ *       customerTier: agentContext.user?.tier || "standard",
+ *     })
+ *   );
+ *   tools = [CreateTicketTool];
+ * }
+ * ```
+ *
+ * @example Template file (instructions/support-agent.md)
+ * ```markdown
+ * You are a customer support agent.
+ *
+ * Customer: {{user.name}} ({{customerTier}})
+ * {{#if user.isPremium}}
+ * ⭐ VIP CUSTOMER - Provide white-glove service!
+ * {{/if}}
+ *
+ * {{#unless isBusinessHours}}
+ * NOTE: Outside business hours. Suggest emergency contact.
+ * {{/unless}}
+ * ```
+ *
+ * @param filePath - Path to instructions file (./ for agent-relative, otherwise project root)
+ * @param variables - Static object or callback returning template variables
+ * @returns InstructionsCallback compatible with FlinkAgent.instructions property
+ */
+function agentInstructions(filePath, variables) {
+    var _this = this;
+    // Resolve path once at definition time for early validation
+    var resolvedPath = resolveFilePath(filePath);
+    // Return callback that will be invoked by FlinkAgent
+    return function (ctx, agentContext) { return __awaiter(_this, void 0, void 0, function () {
+        var cached, vars, templateData;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    cached = loadFile(resolvedPath, filePath);
+                    // Skip template processing entirely when no expressions exist
+                    if (cached.hasTemplateExpressions === false) {
+                        return [2 /*return*/, cached.content];
+                    }
+                    vars = {};
+                    if (!variables) return [3 /*break*/, 3];
+                    if (!(typeof variables === "function")) return [3 /*break*/, 2];
+                    return [4 /*yield*/, Promise.resolve(variables(ctx, agentContext))];
+                case 1:
+                    vars = _a.sent();
+                    return [3 /*break*/, 3];
+                case 2:
+                    vars = variables;
+                    _a.label = 3;
+                case 3:
+                    templateData = __assign(__assign({}, vars), { ctx: ctx, agentContext: agentContext, user: agentContext.user });
+                    // Render template (compiles and caches Handlebars template on first call)
+                    return [2 /*return*/, renderTemplate(cached, templateData, resolvedPath)];
+            }
+        });
+    }); };
+}

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

@@ -0,0 +1,8 @@
+export * from "./FlinkTool";
+export * from "./FlinkAgent";
+export * from "./ConversationAgent";
+export * from "./InMemoryConversationAgent";
+export * from "./ToolExecutor";
+export * from "./AgentRunner";
+export * from "./LLMAdapter";
+export { agentInstructions } from "./agentInstructions";

package/dist/src/ai/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentInstructions = void 0;
+__exportStar(require("./FlinkTool"), exports);
+__exportStar(require("./FlinkAgent"), exports);
+__exportStar(require("./ConversationAgent"), exports);
+__exportStar(require("./InMemoryConversationAgent"), exports);
+__exportStar(require("./ToolExecutor"), exports);
+__exportStar(require("./AgentRunner"), exports);
+__exportStar(require("./LLMAdapter"), exports);
+var agentInstructions_1 = require("./agentInstructions");
+Object.defineProperty(exports, "agentInstructions", { enumerable: true, get: function () { return agentInstructions_1.agentInstructions; } });

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

@@ -0,0 +1,44 @@
+/**
+ * Return type for the FlinkAgent.instructions() method.
+ *
+ * Supported forms:
+ * - `string` — Plain text used as-is, OR a file path (see below) which is auto-loaded.
+ * - `{ file, params? }` — Explicitly load a file with optional Handlebars template params.
+ *
+ * **Path resolution** — all paths resolve relative to the **project root** (`process.cwd()`):
+ * - `"instructions/foo.md"` → `<project-root>/instructions/foo.md`
+ * - `"./instructions/foo.md"` → `<project-root>/instructions/foo.md`
+ * - `"/instructions/foo.md"` → `<project-root>/instructions/foo.md` (leading slash stripped)
+ *
+ * Auto-loaded string extensions: `.md`, `.txt`, `.yaml`, `.yml`, `.xml`, `.toml`, `.ini`, `.json`, `.html`
+ *
+ * @example Plain text
+ * instructions() {
+ *     return "You are a helpful car assistant.";
+ * }
+ *
+ * @example Auto-load file (project-root-relative)
+ * instructions() {
+ *     return "instructions/car-agent.md";
+ * }
+ *
+ * @example File with template params
+ * async instructions(_ctx, agentCtx) {
+ *     return {
+ *         file: "instructions/support.md",
+ *         params: {
+ *             customerTier: agentCtx.user?.tier || "standard",
+ *             isBusinessHours: new Date().getHours() >= 9,
+ *         },
+ *     };
+ * }
+ */
+export type InstructionsReturn = string | {
+    file: string;
+    params?: Record<string, any>;
+};
+/**
+ * Resolve an InstructionsReturn value to a plain string.
+ * @internal Used by FlinkAgent.toAgentProps()
+ */
+export declare function resolveInstructionsReturn(result: InstructionsReturn, ctx: any, agentContext: any): Promise<string>;

package/dist/src/ai/instructionFileLoader.js

@@ -0,0 +1,179 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveInstructionsReturn = resolveInstructionsReturn;
+var fs = __importStar(require("fs"));
+var path = __importStar(require("path"));
+var handlebars_1 = __importDefault(require("handlebars"));
+// Enable {{{{raw}}}}...{{{{/raw}}}} blocks to pass content through unprocessed.
+// Without this, content inside raw blocks is silently dropped.
+handlebars_1.default.registerHelper("raw", function (options) {
+    return options.fn(this);
+});
+var fileCache = new Map();
+var IMPORT_REGEX = /\{\{\s*import\s+["']([^"']+)['"]\s*\}\}/g;
+function resolveImports(content, currentDir, visited) {
+    if (visited === void 0) { visited = new Set(); }
+    return content.replace(IMPORT_REGEX, function (match, importPath) {
+        var resolved = path.resolve(currentDir, importPath);
+        if (visited.has(resolved)) {
+            throw new Error("Circular import detected: ".concat(resolved));
+        }
+        var nextVisited = new Set(visited);
+        nextVisited.add(resolved);
+        try {
+            var importedContent = fs.readFileSync(resolved, "utf-8");
+            return resolveImports(importedContent, path.dirname(resolved), nextVisited);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new Error("Imported markdown file not found: ".concat(resolved, " (imported from: ").concat(currentDir, ")"));
+            }
+            throw err;
+        }
+    });
+}
+/**
+ * Resolve a file path relative to project root (process.cwd()).
+ * Leading `./` and `/` are normalised away — all paths are treated as project-root-relative.
+ */
+function resolveFilePath(filePath) {
+    // Strip leading slash so "/foo.md" behaves the same as "foo.md"
+    var normalised = filePath.replace(/^\/+/, "");
+    return path.resolve(process.cwd(), normalised);
+}
+function loadFile(filePath) {
+    var resolvedPath = resolveFilePath(filePath);
+    try {
+        var stats = fs.statSync(resolvedPath);
+        var mtime = stats.mtimeMs;
+        var cached = fileCache.get(resolvedPath);
+        if (cached && cached.mtime === mtime) {
+            return cached;
+        }
+        var content = fs.readFileSync(resolvedPath, "utf-8");
+        var resolvedContent = resolveImports(content, path.dirname(resolvedPath));
+        var entry = { content: content, resolvedContent: resolvedContent, mtime: mtime };
+        fileCache.set(resolvedPath, entry);
+        return entry;
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new Error("Agent instructions file not found: ".concat(resolvedPath, " (from: ").concat(filePath, ")"));
+        }
+        throw new Error("Failed to load agent instructions file: ".concat(resolvedPath, " - ").concat(err.message));
+    }
+}
+function renderTemplate(entry, data) {
+    if (entry.hasTemplateExpressions === false) {
+        return entry.resolvedContent;
+    }
+    if (!entry.compiledTemplate) {
+        entry.hasTemplateExpressions = /\{\{/.test(entry.resolvedContent);
+        if (!entry.hasTemplateExpressions) {
+            return entry.resolvedContent;
+        }
+        entry.compiledTemplate = handlebars_1.default.compile(entry.resolvedContent);
+    }
+    return entry.compiledTemplate(data);
+}
+var TEXT_FILE_EXTENSIONS = [".md", ".txt", ".yaml", ".yml", ".xml", ".toml", ".ini", ".json", ".html", ".htm"];
+function isTextFilePath(value) {
+    var trimmed = value.trimEnd().toLowerCase();
+    return TEXT_FILE_EXTENSIONS.some(function (ext) { return trimmed.endsWith(ext); });
+}
+/**
+ * Resolve an InstructionsReturn value to a plain string.
+ * @internal Used by FlinkAgent.toAgentProps()
+ */
+function resolveInstructionsReturn(result, ctx, agentContext) {
+    return __awaiter(this, void 0, void 0, function () {
+        var entry_1, templateData_1, file, params, entry, templateData;
+        return __generator(this, function (_a) {
+            if (typeof result === "string") {
+                if (isTextFilePath(result)) {
+                    entry_1 = loadFile(result.trimEnd());
+                    templateData_1 = { ctx: ctx, agentContext: agentContext, user: agentContext === null || agentContext === void 0 ? void 0 : agentContext.user };
+                    return [2 /*return*/, renderTemplate(entry_1, templateData_1)];
+                }
+                return [2 /*return*/, result];
+            }
+            file = result.file, params = result.params;
+            entry = loadFile(file);
+            templateData = __assign(__assign({}, params), { ctx: ctx, agentContext: agentContext, user: agentContext === null || agentContext === void 0 ? void 0 : agentContext.user });
+            return [2 /*return*/, renderTemplate(entry, templateData)];
+        });
+    });
+}

package/dist/src/auth/FlinkAuthPlugin.d.ts

@@ -1,5 +1,5 @@
 import { FlinkRequest } from "../FlinkHttpHandler";
 export interface FlinkAuthPlugin {
-    authenticateRequest: (req: FlinkRequest, permissions: string | string[]) => Promise<boolean>;
+    authenticateRequest: (req: FlinkRequest, permissions: string | string[], ctx?: any) => Promise<boolean>;
     createToken: (payload: any, roles: string[]) => Promise<string>;
 }

package/dist/src/handlers/StreamWriterFactory.d.ts

@@ -0,0 +1,20 @@
+import { Response } from "express";
+import { StreamWriter, StreamFormat } from "../FlinkHttpHandler";
+/**
+ * Factory for creating StreamWriter instances for SSE and NDJSON streaming.
+ *
+ * Handles HTTP headers, connection lifecycle, and format-specific serialization.
+ */
+export declare class StreamWriterFactory {
+    /**
+     * Create a StreamWriter for the given format.
+     *
+     * Sets appropriate HTTP headers and manages the stream lifecycle including
+     * client disconnect detection.
+     *
+     * @param res - Express response object
+     * @param format - Stream format (sse or ndjson)
+     * @returns StreamWriter instance for writing data to the stream
+     */
+    static create<T = any>(res: Response, format: StreamFormat): StreamWriter<T>;
+}

package/dist/src/handlers/StreamWriterFactory.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamWriterFactory = void 0;
+var FlinkLog_1 = require("../FlinkLog");
+/**
+ * Factory for creating StreamWriter instances for SSE and NDJSON streaming.
+ *
+ * Handles HTTP headers, connection lifecycle, and format-specific serialization.
+ */
+var StreamWriterFactory = /** @class */ (function () {
+    function StreamWriterFactory() {
+    }
+    /**
+     * Create a StreamWriter for the given format.
+     *
+     * Sets appropriate HTTP headers and manages the stream lifecycle including
+     * client disconnect detection.
+     *
+     * @param res - Express response object
+     * @param format - Stream format (sse or ndjson)
+     * @returns StreamWriter instance for writing data to the stream
+     */
+    StreamWriterFactory.create = function (res, format) {
+        // Set appropriate headers based on format
+        if (format === "sse") {
+            res.setHeader("Content-Type", "text/event-stream");
+            res.setHeader("Cache-Control", "no-cache");
+            res.setHeader("Connection", "keep-alive");
+            res.flushHeaders();
+        }
+        else if (format === "ndjson") {
+            res.setHeader("Content-Type", "application/x-ndjson");
+            res.setHeader("Cache-Control", "no-cache");
+            res.flushHeaders();
+        }
+        var isOpen = true;
+        // Detect client disconnect
+        res.on("close", function () {
+            isOpen = false;
+        });
+        return {
+            write: function (data) {
+                if (!isOpen)
+                    return;
+                try {
+                    var json = JSON.stringify(data);
+                    if (format === "sse") {
+                        res.write("data: ".concat(json, "\n\n"));
+                    }
+                    else if (format === "ndjson") {
+                        res.write("".concat(json, "\n"));
+                    }
+                }
+                catch (err) {
+                    FlinkLog_1.log.error("StreamWriter serialization error:", { error: err });
+                    isOpen = false;
+                }
+            },
+            error: function (error) {
+                if (!isOpen)
+                    return;
+                var errorMessage = typeof error === "string" ? error : error.message;
+                if (format === "sse") {
+                    res.write("event: error\ndata: ".concat(JSON.stringify({ error: errorMessage }), "\n\n"));
+                }
+                else if (format === "ndjson") {
+                    res.write("".concat(JSON.stringify({ error: errorMessage }), "\n"));
+                }
+                res.end();
+                isOpen = false;
+            },
+            end: function () {
+                if (isOpen) {
+                    res.end();
+                    isOpen = false;
+                }
+            },
+            isOpen: function () { return isOpen; },
+        };
+    };
+    return StreamWriterFactory;
+}());
+exports.StreamWriterFactory = StreamWriterFactory;