@flink-app/flink 2.0.0-alpha.59 → 2.0.0-alpha.60

package/CHANGELOG.md

@@ -1,5 +1,7 @@
 # @flink-app/flink
 
+## 2.0.0-alpha.60
+
 ## 2.0.0-alpha.59
 
 ### Minor Changes

package/cli/dev.ts

@@ -6,6 +6,7 @@ import { existsSync } from "fs";
 import { parseArgs, hasFlag, getOption, normalizeEntry, printHelp, compile, forkApp } from "./cli-utils";
 import { FlinkLogFactory } from "../src/FlinkLogFactory";
 import { loadFlinkConfig } from "../src/utils/loadFlinkConfig";
+import { loadEnvFiles } from "./loadEnvFiles";
 
 // Load config BEFORE creating logger
 const flinkConfig = loadFlinkConfig();
@@ -16,6 +17,19 @@ const logger = FlinkLogFactory.createLogger("flink.dev");
 module.exports = async function dev(args: string[]) {
     const parsed = parseArgs(args);
 
+    // Load .env files before anything else so all env vars are available at startup.
+    // NODE_ENV defaults to "development" when not explicitly set.
+    if (!process.env.NODE_ENV) {
+        process.env.NODE_ENV = "development";
+    }
+
+    const initLogger = FlinkLogFactory.createLogger("flink.init");
+    const { loaded, injected } = loadEnvFiles(parsed.dir, "development");
+
+    if (loaded.length > 0) {
+        initLogger.info(`Loaded env files: ${loaded.join(", ")} (${injected} vars injected)`);
+    }
+
     if (hasFlag(parsed, "help")) {
         printHelp({
             description:

package/cli/loadEnvFiles.ts

@@ -0,0 +1,116 @@
+import { readFileSync, existsSync } from "fs";
+import { resolve, join } from "path";
+
+/**
+ * Parse the contents of a .env file into a key/value map.
+ *
+ * Rules:
+ * - Empty lines and lines starting with # are skipped
+ * - "export FOO=bar" is treated the same as "FOO=bar"
+ * - Quoted values (single or double) are unquoted, and their content is used as-is
+ * - Unquoted values have inline comments stripped: FOO=bar # comment → "bar"
+ */
+export function parseEnvContent(content: string): Record<string, string> {
+    const result: Record<string, string> = {};
+
+    for (const rawLine of content.split("\n")) {
+        let line = rawLine.trim();
+
+        // Skip empty lines and full-line comments
+        if (!line || line.startsWith("#")) continue;
+
+        // Strip "export " prefix
+        if (line.startsWith("export ")) {
+            line = line.slice(7).trim();
+        }
+
+        const eqIdx = line.indexOf("=");
+        if (eqIdx === -1) continue;
+
+        const key = line.slice(0, eqIdx).trim();
+        if (!key) continue;
+
+        let value = line.slice(eqIdx + 1);
+
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            // Quoted value — strip quotes, preserve content as-is
+            value = value.slice(1, -1);
+        } else {
+            // Unquoted — strip inline comments (" # ...") and trim
+            const commentIdx = value.search(/ #/);
+            if (commentIdx !== -1) {
+                value = value.slice(0, commentIdx);
+            }
+            value = value.trim();
+        }
+
+        result[key] = value;
+    }
+
+    return result;
+}
+
+function readEnvFile(filepath: string): Record<string, string> | null {
+    if (!existsSync(filepath)) return null;
+    try {
+        return parseEnvContent(readFileSync(filepath, "utf-8"));
+    } catch {
+        return null;
+    }
+}
+
+export interface LoadEnvFilesResult {
+    /** Relative filenames that were found and loaded, in load order */
+    loaded: string[];
+    /** Number of variables injected into process.env (excludes already-set vars) */
+    injected: number;
+}
+
+/**
+ * Load .env files in Next.js-compatible order.
+ *
+ * Priority (highest wins):
+ *   1. process.env (already-set variables are never overridden)
+ *   2. .env.[environment].local
+ *   3. .env.local               (skipped when environment === "test")
+ *   4. .env.[environment]
+ *   5. .env
+ *
+ * @param dir     Root directory of the Flink app (where .env files live)
+ * @param environment  "development" | "production" | "test"
+ */
+export function loadEnvFiles(dir: string, environment: "development" | "production" | "test"): LoadEnvFilesResult {
+    const absoluteDir = resolve(dir);
+
+    // Files listed from lowest to highest priority so that Object.assign
+    // naturally lets later files override earlier ones.
+    const candidates: string[] = [
+        ".env",
+        `.env.${environment}`,
+        // .env.local is intentionally skipped in test (matches Next.js behaviour)
+        ...(environment !== "test" ? [".env.local"] : []),
+        `.env.${environment}.local`,
+    ];
+
+    const loaded: string[] = [];
+    const merged: Record<string, string> = {};
+
+    for (const filename of candidates) {
+        const parsed = readEnvFile(join(absoluteDir, filename));
+        if (parsed !== null) {
+            loaded.push(filename);
+            Object.assign(merged, parsed);
+        }
+    }
+
+    // Inject into process.env — existing values always win
+    let injected = 0;
+    for (const [key, value] of Object.entries(merged)) {
+        if (!(key in process.env)) {
+            process.env[key] = value;
+            injected++;
+        }
+    }
+
+    return { loaded, injected };
+}

package/cli/run.ts

@@ -2,6 +2,7 @@
 import { parseArgs, hasFlag, getOption, normalizeEntry, printHelp, compile, forkApp } from "./cli-utils";
 import { FlinkLogFactory } from "../src/FlinkLogFactory";
 import { loadFlinkConfig } from "../src/utils/loadFlinkConfig";
+import { loadEnvFiles } from "./loadEnvFiles";
 
 // Load config BEFORE creating logger
 const flinkConfig = loadFlinkConfig();
@@ -10,6 +11,19 @@ FlinkLogFactory.configure(flinkConfig?.logging);
 module.exports = async function run(args: string[]) {
     const parsed = parseArgs(args);
 
+    // Load .env files before anything else so all env vars are available at startup.
+    // NODE_ENV defaults to "production" when not explicitly set.
+    if (!process.env.NODE_ENV) {
+        process.env.NODE_ENV = "production";
+    }
+
+    const initLogger = FlinkLogFactory.createLogger("flink.init");
+    const { loaded, injected } = loadEnvFiles(parsed.dir, "production");
+
+    if (loaded.length > 0) {
+        initLogger.info(`Loaded env files: ${loaded.join(", ")} (${injected} vars injected)`);
+    }
+
     if (hasFlag(parsed, "help")) {
         printHelp({
             description: "Compiles and starts the application.",

package/dist/cli/dev.js

@@ -47,18 +47,29 @@ var fs_1 = require("fs");
 var cli_utils_1 = require("./cli-utils");
 var FlinkLogFactory_1 = require("../src/FlinkLogFactory");
 var loadFlinkConfig_1 = require("../src/utils/loadFlinkConfig");
+var loadEnvFiles_1 = require("./loadEnvFiles");
 // Load config BEFORE creating logger
 var flinkConfig = (0, loadFlinkConfig_1.loadFlinkConfig)();
 FlinkLogFactory_1.FlinkLogFactory.configure(flinkConfig === null || flinkConfig === void 0 ? void 0 : flinkConfig.logging);
 var logger = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.dev");
 module.exports = function dev(args) {
     return __awaiter(this, void 0, void 0, function () {
-        var parsed, dir, entry, typecheck, noTypecheck, serverProcess, tscProcess, isRebuilding, pendingRebuild, watcher;
+        var parsed, initLogger, _a, loaded, injected, dir, entry, typecheck, noTypecheck, serverProcess, tscProcess, isRebuilding, pendingRebuild, watcher;
         var _this = this;
-        return __generator(this, function (_a) {
-            switch (_a.label) {
+        return __generator(this, function (_b) {
+            switch (_b.label) {
                 case 0:
                     parsed = (0, cli_utils_1.parseArgs)(args);
+                    // Load .env files before anything else so all env vars are available at startup.
+                    // NODE_ENV defaults to "development" when not explicitly set.
+                    if (!process.env.NODE_ENV) {
+                        process.env.NODE_ENV = "development";
+                    }
+                    initLogger = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.init");
+                    _a = (0, loadEnvFiles_1.loadEnvFiles)(parsed.dir, "development"), loaded = _a.loaded, injected = _a.injected;
+                    if (loaded.length > 0) {
+                        initLogger.info("Loaded env files: ".concat(loaded.join(", "), " (").concat(injected, " vars injected)"));
+                    }
                     if ((0, cli_utils_1.hasFlag)(parsed, "help")) {
                         (0, cli_utils_1.printHelp)({
                             description: "Starts development mode with watch and auto-reload.\n      Fast rebuilds with swc (skips type checking by default).\n      Runs background tsc --watch for async type error reporting.",
@@ -81,7 +92,7 @@ module.exports = function dev(args) {
                     console.log("\uD83D\uDCE6 Initial build ".concat(typecheck ? "(with type checking)" : "(fast mode, skipping type check)", "..."));
                     return [4 /*yield*/, (0, cli_utils_1.compile)({ dir: dir, entry: entry, typeCheck: typecheck })];
                 case 1:
-                    _a.sent();
+                    _b.sent();
                     serverProcess = null;
                     tscProcess = null;
                     isRebuilding = false;

package/dist/cli/loadEnvFiles.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Parse the contents of a .env file into a key/value map.
+ *
+ * Rules:
+ * - Empty lines and lines starting with # are skipped
+ * - "export FOO=bar" is treated the same as "FOO=bar"
+ * - Quoted values (single or double) are unquoted, and their content is used as-is
+ * - Unquoted values have inline comments stripped: FOO=bar # comment → "bar"
+ */
+export declare function parseEnvContent(content: string): Record<string, string>;
+export interface LoadEnvFilesResult {
+    /** Relative filenames that were found and loaded, in load order */
+    loaded: string[];
+    /** Number of variables injected into process.env (excludes already-set vars) */
+    injected: number;
+}
+/**
+ * Load .env files in Next.js-compatible order.
+ *
+ * Priority (highest wins):
+ *   1. process.env (already-set variables are never overridden)
+ *   2. .env.[environment].local
+ *   3. .env.local               (skipped when environment === "test")
+ *   4. .env.[environment]
+ *   5. .env
+ *
+ * @param dir     Root directory of the Flink app (where .env files live)
+ * @param environment  "development" | "production" | "test"
+ */
+export declare function loadEnvFiles(dir: string, environment: "development" | "production" | "test"): LoadEnvFilesResult;

package/dist/cli/loadEnvFiles.js

@@ -0,0 +1,113 @@
+"use strict";
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEnvContent = parseEnvContent;
+exports.loadEnvFiles = loadEnvFiles;
+var fs_1 = require("fs");
+var path_1 = require("path");
+/**
+ * Parse the contents of a .env file into a key/value map.
+ *
+ * Rules:
+ * - Empty lines and lines starting with # are skipped
+ * - "export FOO=bar" is treated the same as "FOO=bar"
+ * - Quoted values (single or double) are unquoted, and their content is used as-is
+ * - Unquoted values have inline comments stripped: FOO=bar # comment → "bar"
+ */
+function parseEnvContent(content) {
+    var result = {};
+    for (var _i = 0, _a = content.split("\n"); _i < _a.length; _i++) {
+        var rawLine = _a[_i];
+        var line = rawLine.trim();
+        // Skip empty lines and full-line comments
+        if (!line || line.startsWith("#"))
+            continue;
+        // Strip "export " prefix
+        if (line.startsWith("export ")) {
+            line = line.slice(7).trim();
+        }
+        var eqIdx = line.indexOf("=");
+        if (eqIdx === -1)
+            continue;
+        var key = line.slice(0, eqIdx).trim();
+        if (!key)
+            continue;
+        var value = line.slice(eqIdx + 1);
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            // Quoted value — strip quotes, preserve content as-is
+            value = value.slice(1, -1);
+        }
+        else {
+            // Unquoted — strip inline comments (" # ...") and trim
+            var commentIdx = value.search(/ #/);
+            if (commentIdx !== -1) {
+                value = value.slice(0, commentIdx);
+            }
+            value = value.trim();
+        }
+        result[key] = value;
+    }
+    return result;
+}
+function readEnvFile(filepath) {
+    if (!(0, fs_1.existsSync)(filepath))
+        return null;
+    try {
+        return parseEnvContent((0, fs_1.readFileSync)(filepath, "utf-8"));
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/**
+ * Load .env files in Next.js-compatible order.
+ *
+ * Priority (highest wins):
+ *   1. process.env (already-set variables are never overridden)
+ *   2. .env.[environment].local
+ *   3. .env.local               (skipped when environment === "test")
+ *   4. .env.[environment]
+ *   5. .env
+ *
+ * @param dir     Root directory of the Flink app (where .env files live)
+ * @param environment  "development" | "production" | "test"
+ */
+function loadEnvFiles(dir, environment) {
+    var absoluteDir = (0, path_1.resolve)(dir);
+    // Files listed from lowest to highest priority so that Object.assign
+    // naturally lets later files override earlier ones.
+    var candidates = __spreadArray(__spreadArray([
+        ".env",
+        ".env.".concat(environment)
+    ], (environment !== "test" ? [".env.local"] : []), true), [
+        ".env.".concat(environment, ".local"),
+    ], false);
+    var loaded = [];
+    var merged = {};
+    for (var _i = 0, candidates_1 = candidates; _i < candidates_1.length; _i++) {
+        var filename = candidates_1[_i];
+        var parsed = readEnvFile((0, path_1.join)(absoluteDir, filename));
+        if (parsed !== null) {
+            loaded.push(filename);
+            Object.assign(merged, parsed);
+        }
+    }
+    // Inject into process.env — existing values always win
+    var injected = 0;
+    for (var _a = 0, _b = Object.entries(merged); _a < _b.length; _a++) {
+        var _c = _b[_a], key = _c[0], value = _c[1];
+        if (!(key in process.env)) {
+            process.env[key] = value;
+            injected++;
+        }
+    }
+    return { loaded: loaded, injected: injected };
+}

package/dist/cli/run.js

@@ -40,16 +40,27 @@ Object.defineProperty(exports, "__esModule", { value: true });
 var cli_utils_1 = require("./cli-utils");
 var FlinkLogFactory_1 = require("../src/FlinkLogFactory");
 var loadFlinkConfig_1 = require("../src/utils/loadFlinkConfig");
+var loadEnvFiles_1 = require("./loadEnvFiles");
 // Load config BEFORE creating logger
 var flinkConfig = (0, loadFlinkConfig_1.loadFlinkConfig)();
 FlinkLogFactory_1.FlinkLogFactory.configure(flinkConfig === null || flinkConfig === void 0 ? void 0 : flinkConfig.logging);
 module.exports = function run(args) {
     return __awaiter(this, void 0, void 0, function () {
-        var parsed, entry;
-        return __generator(this, function (_a) {
-            switch (_a.label) {
+        var parsed, initLogger, _a, loaded, injected, entry;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
                 case 0:
                     parsed = (0, cli_utils_1.parseArgs)(args);
+                    // Load .env files before anything else so all env vars are available at startup.
+                    // NODE_ENV defaults to "production" when not explicitly set.
+                    if (!process.env.NODE_ENV) {
+                        process.env.NODE_ENV = "production";
+                    }
+                    initLogger = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.init");
+                    _a = (0, loadEnvFiles_1.loadEnvFiles)(parsed.dir, "production"), loaded = _a.loaded, injected = _a.injected;
+                    if (loaded.length > 0) {
+                        initLogger.info("Loaded env files: ".concat(loaded.join(", "), " (").concat(injected, " vars injected)"));
+                    }
                     if ((0, cli_utils_1.hasFlag)(parsed, "help")) {
                         (0, cli_utils_1.printHelp)({
                             description: "Compiles and starts the application.",
@@ -80,7 +91,7 @@ module.exports = function run(args) {
                             typeCheck: true,
                         })];
                 case 1:
-                    _a.sent();
+                    _b.sent();
                     (0, cli_utils_1.forkApp)({
                         dir: parsed.dir,
                         args: args,

package/dist/src/ai/AgentRunner.js

@@ -132,7 +132,7 @@ var AgentRunner = /** @class */ (function () {
                         return [3 /*break*/, 6];
                     case 5:
                         err_1 = _o.sent();
-                        throw new Error("Failed to resolve dynamic instructions for agent ".concat(this.agentName, ": ").concat(err_1.message));
+                        throw new Error("Failed to resolve instructions for agent ".concat(this.agentName, ": ").concat(err_1.message));
                     case 6:
                         if (input.history && input.history.length > 0) {
                             // Start with history

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

@@ -481,8 +481,9 @@ export interface AgentExecuteInput<ConversationCtx = any> {
      */
     conversationContext?: ConversationCtx;
     /**
-     * Previous conversation messages for context
-     * Agent can load this in beforeRun hook based on conversationId
+     * Previous conversation messages for context, in chronological order (oldest first).
+     * The new `message` will be appended after these history messages.
+     * Agent can load this in beforeRun hook based on conversationId.
      */
     history?: Message[];
     /**

package/dist/src/ai/agentInstructions.js

@@ -84,19 +84,25 @@ 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;
-    // Stack: [0] getCallerFilePath, [1] agentInstructions, [2] agent class
-    var callerFrame = stack[2];
-    var fileName = callerFrame === null || callerFrame === void 0 ? void 0 : callerFrame.getFileName();
-    if (!fileName) {
-        throw new Error("Could not determine caller file location for agent-relative path");
+    // 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;
+        }
     }
-    return fileName;
+    throw new Error("Could not determine caller file location for agent-relative path");
 }
 /**
  * Resolve file path based on prefix:
@@ -104,14 +110,33 @@ function getCallerFilePath() {
  * - 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();
-        return path.resolve(path.dirname(callerFile), filePath);
+        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 path.join(process.cwd(), filePath);
+        return cwdResolved;
     }
 }
 /**
@@ -125,12 +150,13 @@ function loadFile(resolvedPath, originalPath) {
         // Check cache
         var cached = fileCache.get(resolvedPath);
         if (cached && cached.mtime === mtime) {
-            return cached.content;
+            return cached;
         }
-        // Read file and update cache
+        // Read file and update cache (clear compiled template on file change)
         var content = fs.readFileSync(resolvedPath, "utf-8");
-        fileCache.set(resolvedPath, { content: content, mtime: mtime });
-        return content;
+        var entry = { content: content, mtime: mtime };
+        fileCache.set(resolvedPath, entry);
+        return entry;
     }
     catch (err) {
         if (err.code === "ENOENT") {
@@ -140,12 +166,22 @@ function loadFile(resolvedPath, originalPath) {
     }
 }
 /**
- * Render template using Handlebars
+ * Render template using Handlebars with compiled template caching.
+ * Skips Handlebars entirely when content has no template expressions.
  */
-function renderTemplate(content, data, filePath) {
+function renderTemplate(cached, data, filePath) {
+    if (cached.hasTemplateExpressions === false) {
+        return cached.content;
+    }
     try {
-        var template = handlebars_1.default.compile(content);
-        return template(data);
+        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));
@@ -221,11 +257,15 @@ function agentInstructions(filePath, variables) {
     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 content, vars, templateData;
+        var cached, vars, templateData;
         return __generator(this, function (_a) {
             switch (_a.label) {
                 case 0:
-                    content = loadFile(resolvedPath, filePath);
+                    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];
@@ -238,8 +278,8 @@ function agentInstructions(filePath, variables) {
                     _a.label = 3;
                 case 3:
                     templateData = __assign(__assign({}, vars), { ctx: ctx, agentContext: agentContext, user: agentContext.user });
-                    // Render template
-                    return [2 /*return*/, renderTemplate(content, templateData, resolvedPath)];
+                    // Render template (compiles and caches Handlebars template on first call)
+                    return [2 /*return*/, renderTemplate(cached, templateData, resolvedPath)];
             }
         });
     }); };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "2.0.0-alpha.59",
+  "version": "2.0.0-alpha.60",
   "description": "Typescript only framework for creating REST-like APIs on top of Express and mongodb",
   "types": "dist/src/index.d.ts",
   "main": "dist/src/index.js",
@@ -56,7 +56,7 @@
     "ts-morph": "24.0.0",
     "uuid": "^8.3.2",
     "zod": "^4.3.6",
-    "@flink-app/ts-source-to-json-schema": "^0.1.5"
+    "@flink-app/ts-source-to-json-schema": "^0.1.6"
   },
   "devDependencies": {
     "@swc/core": "^1.15.17",

package/spec/AgentRunner.spec.ts

@@ -993,7 +993,7 @@ describe("AgentRunner", () => {
                 }
                 fail("Expected error to be thrown");
             } catch (err: any) {
-                expect(err.message).toContain("Failed to resolve dynamic instructions for agent test_agent");
+                expect(err.message).toContain("Failed to resolve instructions for agent test_agent");
                 expect(err.message).toContain("Database connection failed");
             }
         });

package/spec/FlinkAgent.spec.ts

@@ -504,7 +504,7 @@ describe("FlinkAgent", () => {
             (agent as any).ctx = mockCtx;
             agent.__init(new Map([["default", mockLLMAdapter]]), {});
 
-            await expectAsync(agent.query("Hello")).toBeRejectedWithError(/Failed to resolve dynamic instructions/);
+            await expectAsync(agent.query("Hello")).toBeRejectedWithError(/Failed to resolve instructions/);
         });
     });
 

package/src/ai/AgentRunner.ts

@@ -60,7 +60,7 @@ export class AgentRunner {
             resolvedInstructions =
                 typeof this.agentProps.instructions === "function" ? await this.agentProps.instructions(this.ctx, execContext) : this.agentProps.instructions;
         } catch (err: any) {
-            throw new Error(`Failed to resolve dynamic instructions for agent ${this.agentName}: ${err.message}`);
+            throw new Error(`Failed to resolve instructions for agent ${this.agentName}: ${err.message}`);
         }
 
         // Initialize messages from history + new input

package/src/ai/FlinkAgent.ts

@@ -841,8 +841,9 @@ export interface AgentExecuteInput<ConversationCtx = any> {
     conversationContext?: ConversationCtx;
 
     /**
-     * Previous conversation messages for context
-     * Agent can load this in beforeRun hook based on conversationId
+     * Previous conversation messages for context, in chronological order (oldest first).
+     * The new `message` will be appended after these history messages.
+     * Agent can load this in beforeRun hook based on conversationId.
      */
     history?: Message[];
 

package/src/ai/agentInstructions.ts

@@ -10,6 +10,8 @@ import { InstructionsCallback, AgentExecuteContext } from "./FlinkAgent";
 interface FileCacheEntry {
     content: string;
     mtime: number;
+    compiledTemplate?: Handlebars.TemplateDelegate;
+    hasTemplateExpressions?: boolean;
 }
 
 /**
@@ -20,6 +22,9 @@ const fileCache = new Map<string, FileCacheEntry>();
 /**
  * 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(): string {
     const originalPrepareStackTrace = Error.prepareStackTrace;
@@ -27,15 +32,16 @@ function getCallerFilePath(): string {
     const stack = new Error().stack as unknown as NodeJS.CallSite[];
     Error.prepareStackTrace = originalPrepareStackTrace;
 
-    // Stack: [0] getCallerFilePath, [1] agentInstructions, [2] agent class
-    const callerFrame = stack[2];
-    const fileName = callerFrame?.getFileName();
-
-    if (!fileName) {
-        throw new Error("Could not determine caller file location for agent-relative path");
+    // Find first frame outside this file (skips getCallerFilePath, resolveFilePath, agentInstructions)
+    const thisFile = stack[0]?.getFileName();
+    for (let i = 1; i < stack.length; i++) {
+        const fileName = stack[i]?.getFileName();
+        if (fileName && fileName !== thisFile) {
+            return fileName;
+        }
     }
 
-    return fileName;
+    throw new Error("Could not determine caller file location for agent-relative path");
 }
 
 /**
@@ -44,13 +50,36 @@ function getCallerFilePath(): string {
  * - otherwise = project root-relative
  */
 function resolveFilePath(filePath: string): string {
+    // Always try project root-relative first (most intuitive for users)
+    const 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
         const callerFile = getCallerFilePath();
-        return path.resolve(path.dirname(callerFile), filePath);
+        const 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.
+        const distIndex = resolved.lastIndexOf(path.sep + "dist" + path.sep);
+        if (distIndex !== -1) {
+            const sourcePath = resolved.substring(0, distIndex) + resolved.substring(distIndex + 5); // remove "/dist"
+            if (fs.existsSync(sourcePath)) {
+                return sourcePath;
+            }
+        }
+
+        return resolved;
     } else {
         // Project root-relative
-        return path.join(process.cwd(), filePath);
+        return cwdResolved;
     }
 }
 
@@ -58,7 +87,7 @@ function resolveFilePath(filePath: string): string {
  * Load file contents with smart caching
  * Cache is invalidated when file modification time changes
  */
-function loadFile(resolvedPath: string, originalPath: string): string {
+function loadFile(resolvedPath: string, originalPath: string): FileCacheEntry {
     try {
         const stats = fs.statSync(resolvedPath);
         const mtime = stats.mtimeMs;
@@ -66,14 +95,15 @@ function loadFile(resolvedPath: string, originalPath: string): string {
         // Check cache
         const cached = fileCache.get(resolvedPath);
         if (cached && cached.mtime === mtime) {
-            return cached.content;
+            return cached;
         }
 
-        // Read file and update cache
+        // Read file and update cache (clear compiled template on file change)
         const content = fs.readFileSync(resolvedPath, "utf-8");
-        fileCache.set(resolvedPath, { content, mtime });
+        const entry: FileCacheEntry = { content, mtime };
+        fileCache.set(resolvedPath, entry);
 
-        return content;
+        return entry;
     } catch (err: any) {
         if (err.code === "ENOENT") {
             throw new Error(`Agent instructions file not found: ${resolvedPath} (from: ${originalPath})`);
@@ -83,12 +113,23 @@ function loadFile(resolvedPath: string, originalPath: string): string {
 }
 
 /**
- * Render template using Handlebars
+ * Render template using Handlebars with compiled template caching.
+ * Skips Handlebars entirely when content has no template expressions.
  */
-function renderTemplate(content: string, data: any, filePath: string): string {
+function renderTemplate(cached: FileCacheEntry, data: any, filePath: string): string {
+    if (cached.hasTemplateExpressions === false) {
+        return cached.content;
+    }
+
     try {
-        const template = Handlebars.compile(content);
-        return template(data);
+        if (!cached.compiledTemplate) {
+            cached.hasTemplateExpressions = /\{\{/.test(cached.content);
+            if (!cached.hasTemplateExpressions) {
+                return cached.content;
+            }
+            cached.compiledTemplate = Handlebars.compile(cached.content);
+        }
+        return cached.compiledTemplate(data);
     } catch (err: any) {
         throw new Error(`Failed to render template in ${filePath}: ${err.message}`);
     }
@@ -170,7 +211,12 @@ export function agentInstructions<Ctx extends FlinkContext = FlinkContext>(
     // Return callback that will be invoked by FlinkAgent
     return async (ctx: Ctx, agentContext: AgentExecuteContext): Promise<string> => {
         // Load file (uses cache if available and mtime unchanged)
-        const content = loadFile(resolvedPath, filePath);
+        const cached = loadFile(resolvedPath, filePath);
+
+        // Skip template processing entirely when no expressions exist
+        if (cached.hasTemplateExpressions === false) {
+            return cached.content;
+        }
 
         // Resolve variables (static or callback)
         let vars: Record<string, any> = {};
@@ -190,8 +236,8 @@ export function agentInstructions<Ctx extends FlinkContext = FlinkContext>(
             user: agentContext.user,
         };
 
-        // Render template
-        return renderTemplate(content, templateData, resolvedPath);
+        // Render template (compiles and caches Handlebars template on first call)
+        return renderTemplate(cached, templateData, resolvedPath);
     };
 }