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

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @flink-app/flink
 
+## 2.0.0-alpha.62
+
+### Minor Changes
+
+-   Add file-based agent instructions with Handlebars templating
+
+    The `instructions()` method now supports returning a file path or `{ file, params? }` object:
+
+    -   Return a string ending in `.md`, `.txt`, `.yaml`, `.yml`, `.xml`, etc. to auto-load from disk
+    -   Return `{ file: "instructions/agent.md", params: { tier: "premium" } }` for Handlebars templates
+    -   All paths resolve relative to the project root (`process.cwd()`)
+    -   Files are cached with mtime-based invalidation
+    -   Template variables `{{ctx}}`, `{{agentContext}}`, and `{{user}}` are always available
+
+    Also fixes a bug where `getRequestPermissions()` returning `[]` outside a request context
+    would override `user.permissions` in the fallback chain, causing permission checks to fail.
+
+## 2.0.0-alpha.61
+
 ## 2.0.0-alpha.60
 
 ## 2.0.0-alpha.59

package/dist/src/FlinkApp.js

@@ -931,7 +931,7 @@ var FlinkApp = /** @class */ (function () {
     };
     FlinkApp.prototype.registerAutoRegisterableTools = function () {
         return __awaiter(this, void 0, void 0, function () {
-            var ToolExecutor, getRepoInstanceName, schemaManifest, _i, autoRegisteredTools_1, toolFile, toolId, toolInstanceName, metadata, schemas, toolExecutor;
+            var ToolExecutor, getRepoInstanceName, schemaManifest, _i, autoRegisteredTools_1, toolFile, toolId, toolInstanceName, metadata, schemas, allSchemas, toolExecutor;
             return __generator(this, function (_a) {
                 ToolExecutor = require("./ai/ToolExecutor").ToolExecutor;
                 getRepoInstanceName = require("./utils").getRepoInstanceName;
@@ -968,8 +968,9 @@ var FlinkApp = /** @class */ (function () {
                     if ((metadata === null || metadata === void 0 ? void 0 : metadata.outputSchemaName) && !(schemas === null || schemas === void 0 ? void 0 : schemas.outputSchema)) {
                         FlinkLog_1.log.warn("Tool ".concat(toolFile.__file, " references outputSchema \"").concat(metadata.outputSchemaName, "\" but not found in schema universe"));
                     }
-                    toolExecutor = new ToolExecutor(toolFile.Tool, toolFile.default, this.ctx, schemas // Auto-generated schemas from manifest (resolved from definitions)
-                    );
+                    allSchemas = schemaManifest.version === "2.0" ? schemaManifest.schemas : schemaManifest.definitions;
+                    toolExecutor = new ToolExecutor(toolFile.Tool, toolFile.default, this.ctx, schemas, // Auto-generated schemas from manifest (resolved from definitions)
+                    allSchemas);
                     this.tools[toolInstanceName] = toolExecutor;
                     initLog.info("Registered tool ".concat(toolInstanceName, " (").concat(toolId, ")"));
                 }

package/dist/src/FlinkRepo.d.ts

@@ -14,7 +14,7 @@ export declare abstract class FlinkRepo<C extends FlinkContext, Model extends Do
     collection: Collection;
     private _ctx?;
     set ctx(ctx: FlinkContext);
-    get ctx(): FlinkContext;
+    get ctx(): C;
     constructor(collectionName: string, db: Db, client?: MongoClient | undefined);
     findAll(query?: {}): Promise<Model[]>;
     getById(id: string | ObjectId): Promise<Model | null>;

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

@@ -1,5 +1,7 @@
 import { FlinkContext } from "../FlinkContext";
 import { FlinkToolFile, FlinkToolProps } from "./FlinkTool";
+import { type InstructionsReturn } from "./instructionFileLoader";
+export type { InstructionsReturn } from "./instructionFileLoader";
 import { LLMContentBlock, LLMMessage } from "./LLMAdapter";
 import { ToolExecutor } from "./ToolExecutor";
 /**
@@ -241,7 +243,49 @@ export declare abstract class FlinkAgent<Ctx extends FlinkContext, ConversationC
     private _tools?;
     abstract id: string;
     abstract description: string;
-    abstract instructions: AgentInstructions<Ctx>;
+    /**
+     * Define the agent's instructions. Override this method in your agent subclass.
+     *
+     * `ctx` is automatically typed as your app's context — no annotation needed.
+     *
+     * Supported return values:
+     * - `string` — Plain text used as-is
+     * - `string` ending with a known text extension (`.md`, `.txt`, `.yaml`, `.yml`, `.xml`, …) — Auto-loaded from disk (project-root-relative)
+     * - `{ file, params? }` — Explicitly load a file (any extension) with optional Handlebars template params
+     *
+     * @example Plain text
+     * instructions() {
+     *     return "You are a helpful car assistant.";
+     * }
+     *
+     * @example Dynamic instructions using ctx and agentContext
+     * async instructions(ctx, agentContext) {
+     *     const user = await ctx.repos.userRepo.getById(agentContext.user?.id);
+     *     return `You are a support agent for ${user.name}.`;
+     * }
+     *
+     * @example Auto-load file by extension (.md, .txt, .yaml, .yml, .xml, … — path relative to project root)
+     * instructions() {
+     *     return "src/agents/instructions/car-agent.md";
+     * }
+     *
+     * @example File with template params
+     * async instructions(ctx, agentContext) {
+     *     return {
+     *         file: "src/agents/instructions/support.md",
+     *         params: {
+     *             customerTier: agentContext.user?.tier || "standard",
+     *             isBusinessHours: new Date().getHours() >= 9,
+     *         },
+     *     };
+     * }
+     *
+     * @example Agent-file-relative path (use agentInstructions helper)
+     * instructions(ctx, agentContext) {
+     *     return agentInstructions("./instructions/support.md", { date: new Date() })(ctx, agentContext);
+     * }
+     */
+    abstract instructions(ctx: Ctx, agentContext: AgentExecuteContext): Promise<InstructionsReturn> | InstructionsReturn;
     tools?: Array<string | FlinkToolFile | FlinkToolProps>;
     model?: {
         adapterId?: string;

package/dist/src/ai/FlinkAgent.js

@@ -70,8 +70,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlinkAgent = void 0;
 var FlinkErrors_1 = require("../FlinkErrors");
 var FlinkLogFactory_1 = require("../FlinkLogFactory");
+var FlinkRequestContext_1 = require("../FlinkRequestContext");
 var AgentRunner_1 = require("./AgentRunner");
+var instructionFileLoader_1 = require("./instructionFileLoader");
 var logger = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.ai.flink-agent");
+var instructionsLog = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.ai.instructions");
 /**
  * Base class for Flink agents (similar to FlinkRepo pattern)
  *
@@ -340,11 +343,11 @@ var FlinkAgent = /** @class */ (function () {
      */
     FlinkAgent.prototype.execute = function (input) {
         var _this = this;
-        var _a, _b, _c;
-        // Use bound user if not explicitly provided in input
-        var user = (_a = input.user) !== null && _a !== void 0 ? _a : this._boundUser;
-        var userPermissions = (_b = input.userPermissions) !== null && _b !== void 0 ? _b : this._boundUserPermissions;
-        var conversationContext = (_c = input.conversationContext) !== null && _c !== void 0 ? _c : this._boundConversationContext;
+        var _a, _b, _c, _d, _e, _f;
+        // Use bound user if not explicitly provided in input, fall back to AsyncLocalStorage request context
+        var user = (_b = (_a = input.user) !== null && _a !== void 0 ? _a : this._boundUser) !== null && _b !== void 0 ? _b : (0, FlinkRequestContext_1.getRequestUser)();
+        var userPermissions = (_d = (_c = input.userPermissions) !== null && _c !== void 0 ? _c : this._boundUserPermissions) !== null && _d !== void 0 ? _d : (_e = (0, FlinkRequestContext_1.getRequestContext)()) === null || _e === void 0 ? void 0 : _e.userPermissions;
+        var conversationContext = (_f = input.conversationContext) !== null && _f !== void 0 ? _f : this._boundConversationContext;
         var executeInput = __assign(__assign({}, input), { user: user, userPermissions: userPermissions, conversationContext: conversationContext });
         // Permission check
         if (this.permissions) {
@@ -620,11 +623,26 @@ var FlinkAgent = /** @class */ (function () {
         return this.id;
     };
     FlinkAgent.prototype.toAgentProps = function () {
+        var _this = this;
         var _a, _b, _c, _d, _e;
         return {
             id: this.getAgentId(),
             description: this.description,
-            instructions: this.instructions,
+            instructions: function (ctx, agentContext) { return __awaiter(_this, void 0, void 0, function () {
+                var resolved, _a;
+                return __generator(this, function (_b) {
+                    switch (_b.label) {
+                        case 0:
+                            _a = instructionFileLoader_1.resolveInstructionsReturn;
+                            return [4 /*yield*/, Promise.resolve(this.instructions(ctx, agentContext))];
+                        case 1: return [4 /*yield*/, _a.apply(void 0, [_b.sent(), ctx, agentContext])];
+                        case 2:
+                            resolved = _b.sent();
+                            instructionsLog.debug("[".concat(this.getAgentId(), "] Resolved instructions:\n").concat(resolved));
+                            return [2 /*return*/, resolved];
+                    }
+                });
+            }); },
             tools: this.tools,
             model: this.model,
             limits: this.limits,

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

@@ -7,12 +7,14 @@ export declare class ToolExecutor<Ctx extends FlinkContext> {
     private ctx;
     private autoSchemas?;
     private ajv;
+    private compiledInputValidator?;
+    private compiledOutputValidator?;
     constructor(toolProps: FlinkToolProps, toolFn: FlinkTool<Ctx, any, any>, ctx: Ctx, autoSchemas?: {
         inputSchema?: any;
         outputSchema?: any;
         inputTypeHint?: "void" | "any" | "named";
         outputTypeHint?: "void" | "any" | "named";
-    } | undefined);
+    } | undefined, allSchemas?: Record<string, any>);
     /**
      * Execute the tool with input
      * @param input - Tool input data

package/dist/src/ai/ToolExecutor.js

@@ -46,12 +46,39 @@ var FlinkLogFactory_1 = require("../FlinkLogFactory");
 var FlinkRequestContext_1 = require("../FlinkRequestContext");
 var toolLog = FlinkLogFactory_1.FlinkLogFactory.createLogger("flink.ai.tool");
 var ToolExecutor = /** @class */ (function () {
-    function ToolExecutor(toolProps, toolFn, ctx, autoSchemas) {
+    function ToolExecutor(toolProps, toolFn, ctx, autoSchemas, allSchemas) {
         this.toolProps = toolProps;
         this.toolFn = toolFn;
         this.ctx = ctx;
         this.autoSchemas = autoSchemas;
         this.ajv = new ajv_1.default({ allErrors: true });
+        // Pre-populate AJV with all schemas so $ref references resolve across schema boundaries
+        if (allSchemas) {
+            for (var _i = 0, _a = Object.values(allSchemas); _i < _a.length; _i++) {
+                var schema = _a[_i];
+                if (schema && schema.$id) {
+                    try {
+                        this.ajv.addSchema(schema);
+                    }
+                    catch (_b) {
+                        // Ignore duplicate schema errors (schema may already be added)
+                    }
+                }
+            }
+        }
+        // Pre-compile validators once at construction time (not per invocation)
+        if (toolProps.inputJsonSchema) {
+            this.compiledInputValidator = this.ajv.compile(toolProps.inputJsonSchema);
+        }
+        else if (autoSchemas === null || autoSchemas === void 0 ? void 0 : autoSchemas.inputSchema) {
+            this.compiledInputValidator = this.ajv.compile(autoSchemas.inputSchema);
+        }
+        if (toolProps.outputJsonSchema) {
+            this.compiledOutputValidator = this.ajv.compile(toolProps.outputJsonSchema);
+        }
+        else if (autoSchemas === null || autoSchemas === void 0 ? void 0 : autoSchemas.outputSchema) {
+            this.compiledOutputValidator = this.ajv.compile(autoSchemas.outputSchema);
+        }
         // Log when using auto-schemas
         if ((autoSchemas === null || autoSchemas === void 0 ? void 0 : autoSchemas.inputSchema) && !toolProps.inputSchema && !toolProps.inputJsonSchema) {
             toolLog.debug("Tool ".concat(toolProps.id, ": Using auto-generated schemas from type parameters"));
@@ -80,34 +107,33 @@ var ToolExecutor = /** @class */ (function () {
      */
     ToolExecutor.prototype.execute = function (input, overrides) {
         return __awaiter(this, void 0, void 0, function () {
-            var user, userPermissions, conversationContext, hasPermission, validatedInput, validate, valid, errorDetails, validate, valid, errorDetails, errorDetails, result, err_1, validatedData, validate, valid, errorDetails, validate, valid, errorDetails;
-            var _a, _b, _c, _d;
-            return __generator(this, function (_e) {
-                switch (_e.label) {
+            var user, userPermissions, conversationContext, hasPermission, validatedInput, valid, errorDetails, errorDetails, result, err_1, validatedData, valid, errorDetails;
+            var _a, _b, _c;
+            return __generator(this, function (_d) {
+                switch (_d.label) {
                     case 0:
                         user = (_a = overrides === null || overrides === void 0 ? void 0 : overrides.user) !== null && _a !== void 0 ? _a : (0, FlinkRequestContext_1.getRequestUser)();
-                        userPermissions = (_b = overrides === null || overrides === void 0 ? void 0 : overrides.permissions) !== null && _b !== void 0 ? _b : (0, FlinkRequestContext_1.getRequestPermissions)();
+                        userPermissions = (_b = overrides === null || overrides === void 0 ? void 0 : overrides.permissions) !== null && _b !== void 0 ? _b : (_c = (0, FlinkRequestContext_1.getRequestContext)()) === null || _c === void 0 ? void 0 : _c.userPermissions;
                         conversationContext = overrides === null || overrides === void 0 ? void 0 : overrides.conversationContext;
                         if (!this.toolProps.permissions) return [3 /*break*/, 2];
                         return [4 /*yield*/, this.checkPermissionsInternal(input, user, userPermissions)];
                     case 1:
-                        hasPermission = _e.sent();
+                        hasPermission = _d.sent();
                         if (!hasPermission) {
                             toolLog.debug("Tool invocator is missing required permission(s)", this.toolProps.permissions, "user has", userPermissions);
                             throw (0, FlinkErrors_1.forbidden)("Permission denied for tool ".concat(this.toolProps.id), "PERMISSION_DENIED");
                         }
-                        _e.label = 2;
+                        _d.label = 2;
                     case 2:
                         try {
                             if (this.toolProps.inputSchema) {
                                 // Priority 1: Use Zod validation
                                 validatedInput = this.toolProps.inputSchema.parse(input);
                             }
-                            else if (this.toolProps.inputJsonSchema) {
-                                validate = this.ajv.compile(this.toolProps.inputJsonSchema);
-                                valid = validate(input);
+                            else if (this.compiledInputValidator) {
+                                valid = this.compiledInputValidator(input);
                                 if (!valid) {
-                                    errorDetails = this.formatAjvErrors(validate.errors || [], input);
+                                    errorDetails = this.formatAjvErrors(this.compiledInputValidator.errors || [], input);
                                     toolLog.warn("Tool ".concat(this.toolProps.id, " input validation failed:"), errorDetails);
                                     return [2 /*return*/, {
                                             success: false,
@@ -117,20 +143,6 @@ var ToolExecutor = /** @class */ (function () {
                                 }
                                 validatedInput = input;
                             }
-                            else if ((_c = this.autoSchemas) === null || _c === void 0 ? void 0 : _c.inputSchema) {
-                                validate = this.ajv.compile(this.autoSchemas.inputSchema);
-                                valid = validate(input);
-                                if (!valid) {
-                                    errorDetails = this.formatAjvErrors(validate.errors || [], input);
-                                    toolLog.warn("Tool ".concat(this.toolProps.id, " input validation failed (auto-generated schema):"), errorDetails);
-                                    return [2 /*return*/, {
-                                            success: false,
-                                            error: "Invalid input for tool '".concat(this.toolProps.id, "': ").concat(errorDetails),
-                                            code: "VALIDATION_ERROR",
-                                        }];
-                                }
-                                validatedInput = input;
-                            }
                             else {
                                 // No schema available - skip validation
                                 validatedInput = input;
@@ -147,9 +159,9 @@ var ToolExecutor = /** @class */ (function () {
                         }
                         // 3. Execute tool
                         toolLog.debug("Executing tool ".concat(this.toolProps.id));
-                        _e.label = 3;
+                        _d.label = 3;
                     case 3:
-                        _e.trys.push([3, 5, , 6]);
+                        _d.trys.push([3, 5, , 6]);
                         toolLog.trace(this.toolFn.name + " input:", validatedInput);
                         return [4 /*yield*/, this.toolFn({
                                 input: validatedInput,
@@ -159,10 +171,10 @@ var ToolExecutor = /** @class */ (function () {
                                 conversationCtx: conversationContext,
                             })];
                     case 4:
-                        result = _e.sent();
+                        result = _d.sent();
                         return [3 /*break*/, 6];
                     case 5:
-                        err_1 = _e.sent();
+                        err_1 = _d.sent();
                         toolLog.error("Tool ".concat(this.toolProps.id, " threw error:"), err_1.message);
                         return [2 /*return*/, {
                                 success: false,
@@ -191,13 +203,12 @@ var ToolExecutor = /** @class */ (function () {
                                     }];
                             }
                         }
-                        else if (this.toolProps.outputJsonSchema) {
-                            // Priority 2: Use manual JSON Schema validation
+                        else if (this.compiledOutputValidator) {
+                            // Priority 2 & 3: Use pre-compiled JSON Schema validator (manual or auto-generated)
                             try {
-                                validate = this.ajv.compile(this.toolProps.outputJsonSchema);
-                                valid = validate(result.data);
+                                valid = this.compiledOutputValidator(result.data);
                                 if (!valid) {
-                                    errorDetails = this.formatAjvErrors(validate.errors || []);
+                                    errorDetails = this.formatAjvErrors(this.compiledOutputValidator.errors || []);
                                     toolLog.error("Tool ".concat(this.toolProps.id, " output validation failed:"), errorDetails);
                                     return [2 /*return*/, {
                                             success: false,
@@ -216,31 +227,6 @@ var ToolExecutor = /** @class */ (function () {
                                     }];
                             }
                         }
-                        else if ((_d = this.autoSchemas) === null || _d === void 0 ? void 0 : _d.outputSchema) {
-                            // Priority 3: Use auto-generated JSON Schema validation
-                            try {
-                                validate = this.ajv.compile(this.autoSchemas.outputSchema);
-                                valid = validate(result.data);
-                                if (!valid) {
-                                    errorDetails = this.formatAjvErrors(validate.errors || []);
-                                    toolLog.error("Tool ".concat(this.toolProps.id, " output validation failed (auto-generated schema):"), errorDetails);
-                                    return [2 /*return*/, {
-                                            success: false,
-                                            error: "Invalid output from tool ".concat(this.toolProps.id, ": ").concat(errorDetails),
-                                            code: "OUTPUT_VALIDATION_ERROR",
-                                        }];
-                                }
-                                return [2 /*return*/, { success: true, data: result.data }];
-                            }
-                            catch (err) {
-                                toolLog.error("Tool ".concat(this.toolProps.id, " output validation failed:"), err.message);
-                                return [2 /*return*/, {
-                                        success: false,
-                                        error: "Invalid output from tool ".concat(this.toolProps.id, ": ").concat(err.message),
-                                        code: "OUTPUT_VALIDATION_ERROR",
-                                    }];
-                            }
-                        }
                         // No output validation - return result as-is
                         return [2 /*return*/, result];
                 }

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

@@ -65,4 +65,4 @@ import { InstructionsCallback, AgentExecuteContext } from "./FlinkAgent";
  * @returns InstructionsCallback compatible with FlinkAgent.instructions property
  */
 export declare function agentInstructions<Ctx extends FlinkContext = FlinkContext>(filePath: string, variables?: Record<string, any> | ((ctx: Ctx, agentContext: AgentExecuteContext) => Record<string, any> | Promise<Record<string, any>>)): InstructionsCallback<Ctx>;
-export type { InstructionsCallback, AgentExecuteContext } from "./FlinkAgent";
+export type { InstructionsCallback, AgentExecuteContext, InstructionsReturn } from "./FlinkAgent";

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,151 @@
+"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"));
+var fileCache = new Map();
+/**
+ * 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 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(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.content;
+    }
+    if (!entry.compiledTemplate) {
+        entry.hasTemplateExpressions = /\{\{/.test(entry.content);
+        if (!entry.hasTemplateExpressions) {
+            return entry.content;
+        }
+        entry.compiledTemplate = handlebars_1.default.compile(entry.content);
+    }
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/flink",
-  "version": "2.0.0-alpha.60",
+  "version": "2.0.0-alpha.62",
   "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",

package/spec/AgentDescendantDetection.spec.ts

@@ -166,7 +166,7 @@ describe("Agent Descendant Detection", () => {
                 export default class MyAgent extends InMemoryConversationAgent<any> {
                     id = "my-agent";
                     description = "Test agent";
-                    instructions = "You are helpful";
+                    instructions() { return "You are helpful"; }
                 }
             `;
             testAgentDetection(source, true);
@@ -182,7 +182,7 @@ describe("Agent Descendant Detection", () => {
                 export default class MyAgent extends InMemoryConversationAgent<AppContext> {
                     id = "my-agent";
                     description = "Test agent";
-                    instructions = "You are helpful";
+                    instructions() { return "You are helpful"; }
                 }
             `;
             testAgentDetection(source, true);

package/spec/AgentRunner.spec.ts

@@ -158,7 +158,7 @@ describe("AgentRunner", () => {
                 input: { city: "Stockholm" },
                 ctx: mockCtx,
                 user: undefined,
-                permissions: [],
+                permissions: undefined,
                 conversationCtx: undefined,
             });
         });

package/spec/ConversationHooks.spec.ts

@@ -34,7 +34,7 @@ describe("Conversation Hooks", () => {
             class TestAgent extends FlinkAgent<FlinkContext> {
                 id = "test-agent";
                 description = "Test agent";
-                instructions = "Test instructions";
+                instructions() { return "Test instructions"; }
                 tools: string[] = [];
 
                 protected beforeRun = beforeRunSpy;
@@ -71,7 +71,7 @@ describe("Conversation Hooks", () => {
             class TestAgent extends FlinkAgent<FlinkContext> {
                 id = "test-agent";
                 description = "Test agent";
-                instructions = "Test instructions";
+                instructions() { return "Test instructions"; }
                 tools: string[] = [];
 
                 protected async beforeRun(input: AgentExecuteInput, context: AgentExecuteContext) {
@@ -139,7 +139,7 @@ describe("Conversation Hooks", () => {
             class TestAgent extends FlinkAgent<FlinkContext> {
                 id = "test-agent";
                 description = "Test agent";
-                instructions = "Test instructions";
+                instructions() { return "Test instructions"; }
                 tools: string[] = ["test_tool"];
 
                 protected onStep = onStepSpy;
@@ -177,7 +177,7 @@ describe("Conversation Hooks", () => {
             class TestAgent extends FlinkAgent<FlinkContext> {
                 id = "test-agent";
                 description = "Test agent";
-                instructions = "Test instructions";
+                instructions() { return "Test instructions"; }
                 tools: string[] = [];
 
                 protected afterRun = afterRunSpy;
@@ -216,7 +216,7 @@ describe("Conversation Hooks", () => {
             class TestAgent extends FlinkAgent<FlinkContext> {
                 id = "test-agent";
                 description = "Test agent";
-                instructions = "Test instructions";
+                instructions() { return "Test instructions"; }
                 tools: string[] = [];
 
                 protected beforeRun = beforeRunSpy;

package/spec/FlinkAgent.spec.ts

@@ -31,7 +31,7 @@ describe("FlinkAgent", () => {
         class TestAgent extends FlinkAgent<FlinkContext> {
             id = "test-agent";
             description = "Test agent";
-            instructions = "Test instructions";
+            instructions() { return "Test instructions"; }
             tools: string[] = [];
 
             async query(message: string) {
@@ -131,7 +131,7 @@ describe("FlinkAgent", () => {
         class TestAgent extends FlinkAgent<FlinkContext> {
             id = "test-agent";
             description = "Test agent";
-            instructions = "Test instructions";
+            instructions() { return "Test instructions"; }
             tools: string[] = ["public_tool", "admin_tool"];
 
             async query(message: string) {
@@ -250,7 +250,7 @@ describe("FlinkAgent", () => {
             class TestAgentWithToolRef extends FlinkAgent<FlinkContext> {
                 id = "test-agent";
                 description = "Test agent";
-                instructions = "Test instructions";
+                instructions() { return "Test instructions"; }
                 tools = [mockToolFile]; // Direct tool file reference!
 
                 async query(message: string) {
@@ -290,7 +290,7 @@ describe("FlinkAgent", () => {
             class MixedToolsAgent extends FlinkAgent<FlinkContext> {
                 id = "test-agent";
                 description = "Test agent";
-                instructions = "Test instructions";
+                instructions() { return "Test instructions"; }
                 tools = [
                     mockToolFile, // File reference
                     "tool-by-string", // String ID
@@ -317,7 +317,7 @@ describe("FlinkAgent", () => {
             class StaticAgent extends FlinkAgent<FlinkContext> {
                 id = "test-agent";
                 description = "Static agent";
-                instructions = "Static instructions";
+                instructions() { return "Static instructions"; }
                 tools: string[] = [];
 
                 async query(message: string) {
@@ -342,9 +342,9 @@ describe("FlinkAgent", () => {
             class DynamicAgent extends FlinkAgent<FlinkContext> {
                 id = "test-agent";
                 description = "Dynamic agent";
-                instructions = (ctx: FlinkContext, agentContext: any) => {
+                instructions(ctx: FlinkContext, agentContext: any) {
                     return `You are a support agent for user ${agentContext.user?.name || "unknown"}`;
-                };
+                }
                 tools: string[] = [];
 
                 async query(message: string) {
@@ -380,13 +380,13 @@ describe("FlinkAgent", () => {
             class DatabaseAgent extends FlinkAgent<any> {
                 id = "test-agent";
                 description = "Database agent";
-                instructions = async (ctx: any, agentContext: any) => {
+                async instructions(ctx: any, agentContext: any) {
                     if (!agentContext.user) {
                         return "You are a support agent.";
                     }
                     const profile = await ctx.repos.userRepo.getById(agentContext.user.id);
                     return `You are a support agent. Customer: ${profile.name}, Tier: ${profile.tier}`;
-                };
+                }
                 tools: string[] = [];
 
                 async query(message: string) {
@@ -415,10 +415,10 @@ describe("FlinkAgent", () => {
             class CachedAgent extends FlinkAgent<FlinkContext> {
                 id = "test-agent";
                 description = "Cached agent";
-                instructions = (ctx: FlinkContext, agentContext: any) => {
+                instructions(ctx: FlinkContext, agentContext: any) {
                     callCount++;
                     return `Instructions for user ${agentContext.user?.name || "unknown"}`;
-                };
+                }
                 tools: string[] = [];
 
                 async query(message: string) {
@@ -461,10 +461,10 @@ describe("FlinkAgent", () => {
             class ConversationAgent extends FlinkAgent<FlinkContext> {
                 id = "test-agent";
                 description = "Conversation agent";
-                instructions = (ctx: FlinkContext, agentContext: any) => {
+                instructions(ctx: FlinkContext, agentContext: any) {
                     capturedContext = agentContext;
                     return `Conversation: ${agentContext.conversationId || "new"}`;
-                };
+                }
                 tools: string[] = [];
 
                 async query(message: string, conversationId?: string) {
@@ -489,9 +489,9 @@ describe("FlinkAgent", () => {
             class ErrorAgent extends FlinkAgent<FlinkContext> {
                 id = "test-agent";
                 description = "Error agent";
-                instructions = () => {
+                instructions(): string {
                     throw new Error("Database unavailable");
-                };
+                }
                 tools: string[] = [];
 
                 async query(message: string) {
@@ -518,7 +518,7 @@ describe("FlinkAgent", () => {
         class TestAgent extends FlinkAgent<FlinkContext, TestConversationContext> {
             id = "test-agent";
             description = "Test agent";
-            instructions = "Test instructions";
+            instructions() { return "Test instructions"; }
             tools: string[] = [];
 
             async query(message: string) {

package/spec/StreamingIntegration.spec.ts

@@ -15,7 +15,7 @@ describe("Streaming Integration", () => {
   class StreamingTestAgent extends FlinkAgent<FlinkContext> {
     id = "streaming-test-agent";
     description = "Test agent for streaming";
-    instructions = "You are a test agent";
+    instructions() { return "You are a test agent"; }
     tools = [];
 
     async query(message: string) {

package/spec/ai/ContextCompaction.spec.ts

@@ -7,7 +7,7 @@ import { LLMAdapter, LLMMessage } from "../../src/ai/LLMAdapter";
 class CompactingAgent extends FlinkAgent<FlinkContext> {
     id = "compacting-agent";
     description = "Test agent with context compaction";
-    instructions = "You are a test assistant";
+    instructions() { return "You are a test assistant"; }
 
     setCallbacks(
         shouldCompact?: (messages: LLMMessage[], step: number) => boolean | Promise<boolean>,

package/spec/ai/ConversationAgent.spec.ts

@@ -9,7 +9,7 @@ import {
 class MockConversationAgent extends ConversationAgent<FlinkContext> {
     id = "mock-agent";
     description = "Mock agent for testing";
-    instructions = "You are a test agent";
+    instructions() { return "You are a test agent"; }
     tools = [];
 
     // Spy methods

package/spec/ai/InMemoryConversationAgent.spec.ts

@@ -3,7 +3,7 @@ import { InMemoryConversationAgent, FlinkContext } from "../../src";
 class TestAgent extends InMemoryConversationAgent<FlinkContext> {
     id = "test-agent";
     description = "Test agent";
-    instructions = "You are a test agent";
+    instructions() { return "You are a test agent"; }
     tools = [];
 }
 

package/spec/fixtures/agent-instructions/TestAgent.ts

@@ -8,15 +8,17 @@ export default class TestAgent extends FlinkAgent<FlinkContext> {
     // Load instructions from file using project-root path
     // Note: For relative paths (./) to work, they must be called from the agent file itself
     // Since this is loaded via require() from test, we use project-root path
-    instructions = agentInstructions(
-        "spec/fixtures/agent-instructions/template.md",
-        (ctx, agentContext) => ({
-            tier: agentContext.user?.tier || "basic",
-            isPremium: agentContext.user?.tier === "premium",
-            isBusinessHours: true,
-            tools: ["test-tool-1", "test-tool-2"],
-        })
-    );
+    instructions(ctx: FlinkContext, agentContext: any) {
+        return agentInstructions(
+            "spec/fixtures/agent-instructions/template.md",
+            (ctx, agentContext) => ({
+                tier: agentContext.user?.tier || "basic",
+                isPremium: agentContext.user?.tier === "premium",
+                isBusinessHours: true,
+                tools: ["test-tool-1", "test-tool-2"],
+            })
+        )(ctx, agentContext);
+    }
 
     tools = [];
 }

package/src/FlinkApp.ts

@@ -1270,11 +1270,15 @@ export class FlinkApp<C extends FlinkContext> {
                 log.warn(`Tool ${toolFile.__file} references outputSchema "${metadata.outputSchemaName}" but not found in schema universe`);
             }
 
+            // Pass full schema universe so AJV can resolve $ref across schemas
+            const allSchemas = schemaManifest.version === "2.0" ? schemaManifest.schemas : schemaManifest.definitions;
+
             const toolExecutor = new ToolExecutor(
                 toolFile.Tool,
                 toolFile.default,
                 this.ctx,
-                schemas // Auto-generated schemas from manifest (resolved from definitions)
+                schemas, // Auto-generated schemas from manifest (resolved from definitions)
+                allSchemas
             );
             this.tools[toolInstanceName] = toolExecutor;
 

package/src/FlinkRepo.ts

@@ -16,7 +16,7 @@ export abstract class FlinkRepo<C extends FlinkContext, Model extends Document>
         this._ctx = ctx as C;
     }
 
-    get ctx() {
+    get ctx(): C {
         if (!this._ctx) throw new Error("Missing FlinkContext");
         return this._ctx;
     }

package/src/ai/FlinkAgent.ts

@@ -1,12 +1,16 @@
 import { FlinkContext } from "../FlinkContext";
 import { forbidden } from "../FlinkErrors";
 import { FlinkLogFactory } from "../FlinkLogFactory";
+import { getRequestContext, getRequestUser } from "../FlinkRequestContext";
 import { AgentRunner } from "./AgentRunner";
 import { FlinkToolFile, FlinkToolProps } from "./FlinkTool";
+import { resolveInstructionsReturn, type InstructionsReturn } from "./instructionFileLoader";
+export type { InstructionsReturn } from "./instructionFileLoader";
 import { LLMContentBlock, LLMMessage } from "./LLMAdapter";
 import { ToolExecutor } from "./ToolExecutor";
 
 const logger = FlinkLogFactory.createLogger("flink.ai.flink-agent");
+const instructionsLog = FlinkLogFactory.createLogger("flink.ai.instructions");
 
 /**
  * Callback function for dynamic instruction generation
@@ -261,7 +265,50 @@ export abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any
     // Abstract properties (must be defined by subclass)
     abstract id: string;
     abstract description: string;
-    abstract instructions: AgentInstructions<Ctx>;
+
+    /**
+     * Define the agent's instructions. Override this method in your agent subclass.
+     *
+     * `ctx` is automatically typed as your app's context — no annotation needed.
+     *
+     * Supported return values:
+     * - `string` — Plain text used as-is
+     * - `string` ending with a known text extension (`.md`, `.txt`, `.yaml`, `.yml`, `.xml`, …) — Auto-loaded from disk (project-root-relative)
+     * - `{ file, params? }` — Explicitly load a file (any extension) with optional Handlebars template params
+     *
+     * @example Plain text
+     * instructions() {
+     *     return "You are a helpful car assistant.";
+     * }
+     *
+     * @example Dynamic instructions using ctx and agentContext
+     * async instructions(ctx, agentContext) {
+     *     const user = await ctx.repos.userRepo.getById(agentContext.user?.id);
+     *     return `You are a support agent for ${user.name}.`;
+     * }
+     *
+     * @example Auto-load file by extension (.md, .txt, .yaml, .yml, .xml, … — path relative to project root)
+     * instructions() {
+     *     return "src/agents/instructions/car-agent.md";
+     * }
+     *
+     * @example File with template params
+     * async instructions(ctx, agentContext) {
+     *     return {
+     *         file: "src/agents/instructions/support.md",
+     *         params: {
+     *             customerTier: agentContext.user?.tier || "standard",
+     *             isBusinessHours: new Date().getHours() >= 9,
+     *         },
+     *     };
+     * }
+     *
+     * @example Agent-file-relative path (use agentInstructions helper)
+     * instructions(ctx, agentContext) {
+     *     return agentInstructions("./instructions/support.md", { date: new Date() })(ctx, agentContext);
+     * }
+     */
+    abstract instructions(ctx: Ctx, agentContext: AgentExecuteContext): Promise<InstructionsReturn> | InstructionsReturn;
 
     // Optional properties
     tools?: Array<string | FlinkToolFile | FlinkToolProps>; // Tool ids, tool file references, or tool props (defaults to empty array)
@@ -471,9 +518,9 @@ export abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any
      *   for await (const chunk of response.fullStream) { ... }  // Stream all events
      */
     protected execute(input: AgentExecuteInput<ConversationCtx>): AgentResponse {
-        // Use bound user if not explicitly provided in input
-        const user = input.user ?? this._boundUser;
-        const userPermissions = input.userPermissions ?? this._boundUserPermissions;
+        // Use bound user if not explicitly provided in input, fall back to AsyncLocalStorage request context
+        const user = input.user ?? this._boundUser ?? getRequestUser();
+        const userPermissions = input.userPermissions ?? this._boundUserPermissions ?? getRequestContext()?.userPermissions;
         const conversationContext = input.conversationContext ?? this._boundConversationContext;
         const executeInput = { ...input, user, userPermissions, conversationContext };
 
@@ -699,7 +746,11 @@ export abstract class FlinkAgent<Ctx extends FlinkContext, ConversationCtx = any
         return {
             id: this.getAgentId(),
             description: this.description,
-            instructions: this.instructions,
+            instructions: async (ctx, agentContext) => {
+                const resolved = await resolveInstructionsReturn(await Promise.resolve(this.instructions(ctx as Ctx, agentContext)), ctx, agentContext);
+                instructionsLog.debug(`[${this.getAgentId()}] Resolved instructions:\n${resolved}`);
+                return resolved;
+            },
             tools: this.tools,
             model: this.model,
             limits: this.limits,

package/src/ai/ToolExecutor.ts

@@ -2,7 +2,7 @@ import Ajv from "ajv";
 import { FlinkContext } from "../FlinkContext";
 import { forbidden } from "../FlinkErrors";
 import { FlinkLogFactory } from "../FlinkLogFactory";
-import { getRequestPermissions, getRequestUser } from "../FlinkRequestContext";
+import { getRequestContext, getRequestUser } from "../FlinkRequestContext";
 import { FlinkTool, FlinkToolProps, ToolResult } from "./FlinkTool";
 import { FlinkToolSchema } from "./LLMAdapter";
 
@@ -10,6 +10,8 @@ const toolLog = FlinkLogFactory.createLogger("flink.ai.tool");
 
 export class ToolExecutor<Ctx extends FlinkContext> {
     private ajv = new Ajv({ allErrors: true });
+    private compiledInputValidator?: ReturnType<Ajv["compile"]>;
+    private compiledOutputValidator?: ReturnType<Ajv["compile"]>;
 
     constructor(
         private toolProps: FlinkToolProps,
@@ -20,8 +22,34 @@ export class ToolExecutor<Ctx extends FlinkContext> {
             outputSchema?: any;
             inputTypeHint?: 'void' | 'any' | 'named';
             outputTypeHint?: 'void' | 'any' | 'named';
-        }
+        },
+        allSchemas?: Record<string, any>
     ) {
+        // Pre-populate AJV with all schemas so $ref references resolve across schema boundaries
+        if (allSchemas) {
+            for (const schema of Object.values(allSchemas)) {
+                if (schema && schema.$id) {
+                    try {
+                        this.ajv.addSchema(schema);
+                    } catch {
+                        // Ignore duplicate schema errors (schema may already be added)
+                    }
+                }
+            }
+        }
+
+        // Pre-compile validators once at construction time (not per invocation)
+        if (toolProps.inputJsonSchema) {
+            this.compiledInputValidator = this.ajv.compile(toolProps.inputJsonSchema);
+        } else if (autoSchemas?.inputSchema) {
+            this.compiledInputValidator = this.ajv.compile(autoSchemas.inputSchema);
+        }
+
+        if (toolProps.outputJsonSchema) {
+            this.compiledOutputValidator = this.ajv.compile(toolProps.outputJsonSchema);
+        } else if (autoSchemas?.outputSchema) {
+            this.compiledOutputValidator = this.ajv.compile(autoSchemas.outputSchema);
+        }
         // Log when using auto-schemas
         if (autoSchemas?.inputSchema && !toolProps.inputSchema && !toolProps.inputJsonSchema) {
             toolLog.debug(`Tool ${toolProps.id}: Using auto-generated schemas from type parameters`);
@@ -56,7 +84,7 @@ export class ToolExecutor<Ctx extends FlinkContext> {
     async execute(input: any, overrides?: { user?: any; permissions?: string[]; conversationContext?: any }): Promise<ToolResult<any>> {
         // Get user, permissions, and conversationContext from AsyncLocalStorage or overrides
         const user = overrides?.user ?? getRequestUser();
-        const userPermissions = overrides?.permissions ?? getRequestPermissions();
+        const userPermissions = overrides?.permissions ?? getRequestContext()?.userPermissions;
         const conversationContext = overrides?.conversationContext;
 
         // 1. Permission check
@@ -74,12 +102,11 @@ export class ToolExecutor<Ctx extends FlinkContext> {
             if (this.toolProps.inputSchema) {
                 // Priority 1: Use Zod validation
                 validatedInput = this.toolProps.inputSchema.parse(input);
-            } else if (this.toolProps.inputJsonSchema) {
-                // Priority 2: Use manual JSON Schema validation
-                const validate = this.ajv.compile(this.toolProps.inputJsonSchema);
-                const valid = validate(input);
+            } else if (this.compiledInputValidator) {
+                // Priority 2 & 3: Use pre-compiled JSON Schema validator (manual or auto-generated)
+                const valid = this.compiledInputValidator(input);
                 if (!valid) {
-                    const errorDetails = this.formatAjvErrors(validate.errors || [], input);
+                    const errorDetails = this.formatAjvErrors(this.compiledInputValidator.errors || [], input);
                     toolLog.warn(`Tool ${this.toolProps.id} input validation failed:`, errorDetails);
                     return {
                         success: false,
@@ -88,20 +115,6 @@ export class ToolExecutor<Ctx extends FlinkContext> {
                     };
                 }
                 validatedInput = input;
-            } else if (this.autoSchemas?.inputSchema) {
-                // Priority 3: Use auto-generated JSON Schema validation
-                const validate = this.ajv.compile(this.autoSchemas.inputSchema);
-                const valid = validate(input);
-                if (!valid) {
-                    const errorDetails = this.formatAjvErrors(validate.errors || [], input);
-                    toolLog.warn(`Tool ${this.toolProps.id} input validation failed (auto-generated schema):`, errorDetails);
-                    return {
-                        success: false,
-                        error: `Invalid input for tool '${this.toolProps.id}': ${errorDetails}`,
-                        code: "VALIDATION_ERROR",
-                    };
-                }
-                validatedInput = input;
             } else {
                 // No schema available - skip validation
                 validatedInput = input;
@@ -161,13 +174,12 @@ export class ToolExecutor<Ctx extends FlinkContext> {
                     code: "OUTPUT_VALIDATION_ERROR",
                 };
             }
-        } else if (this.toolProps.outputJsonSchema) {
-            // Priority 2: Use manual JSON Schema validation
+        } else if (this.compiledOutputValidator) {
+            // Priority 2 & 3: Use pre-compiled JSON Schema validator (manual or auto-generated)
             try {
-                const validate = this.ajv.compile(this.toolProps.outputJsonSchema);
-                const valid = validate(result.data);
+                const valid = this.compiledOutputValidator(result.data);
                 if (!valid) {
-                    const errorDetails = this.formatAjvErrors(validate.errors || []);
+                    const errorDetails = this.formatAjvErrors(this.compiledOutputValidator.errors || []);
                     toolLog.error(`Tool ${this.toolProps.id} output validation failed:`, errorDetails);
                     return {
                         success: false,
@@ -184,29 +196,6 @@ export class ToolExecutor<Ctx extends FlinkContext> {
                     code: "OUTPUT_VALIDATION_ERROR",
                 };
             }
-        } else if (this.autoSchemas?.outputSchema) {
-            // Priority 3: Use auto-generated JSON Schema validation
-            try {
-                const validate = this.ajv.compile(this.autoSchemas.outputSchema);
-                const valid = validate(result.data);
-                if (!valid) {
-                    const errorDetails = this.formatAjvErrors(validate.errors || []);
-                    toolLog.error(`Tool ${this.toolProps.id} output validation failed (auto-generated schema):`, errorDetails);
-                    return {
-                        success: false,
-                        error: `Invalid output from tool ${this.toolProps.id}: ${errorDetails}`,
-                        code: "OUTPUT_VALIDATION_ERROR",
-                    };
-                }
-                return { success: true, data: result.data };
-            } catch (err: any) {
-                toolLog.error(`Tool ${this.toolProps.id} output validation failed:`, err.message);
-                return {
-                    success: false,
-                    error: `Invalid output from tool ${this.toolProps.id}: ${err.message}`,
-                    code: "OUTPUT_VALIDATION_ERROR",
-                };
-            }
         }
 
         // No output validation - return result as-is

package/src/ai/agentInstructions.ts

@@ -242,4 +242,4 @@ export function agentInstructions<Ctx extends FlinkContext = FlinkContext>(
 }
 
 // Re-export types for convenience
-export type { InstructionsCallback, AgentExecuteContext } from "./FlinkAgent";
+export type { InstructionsCallback, AgentExecuteContext, InstructionsReturn } from "./FlinkAgent";

package/src/ai/instructionFileLoader.ts

@@ -0,0 +1,126 @@
+import * as fs from "fs";
+import * as path from "path";
+import Handlebars from "handlebars";
+
+/**
+ * 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> };
+
+interface FileCacheEntry {
+    content: string;
+    mtime: number;
+    compiledTemplate?: Handlebars.TemplateDelegate;
+    hasTemplateExpressions?: boolean;
+}
+
+const fileCache = new Map<string, FileCacheEntry>();
+
+/**
+ * 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: string): string {
+    // Strip leading slash so "/foo.md" behaves the same as "foo.md"
+    const normalised = filePath.replace(/^\/+/, "");
+    return path.resolve(process.cwd(), normalised);
+}
+
+function loadFile(filePath: string): FileCacheEntry {
+    const resolvedPath = resolveFilePath(filePath);
+    try {
+        const stats = fs.statSync(resolvedPath);
+        const mtime = stats.mtimeMs;
+
+        const cached = fileCache.get(resolvedPath);
+        if (cached && cached.mtime === mtime) {
+            return cached;
+        }
+
+        const content = fs.readFileSync(resolvedPath, "utf-8");
+        const entry: FileCacheEntry = { content, mtime };
+        fileCache.set(resolvedPath, entry);
+        return entry;
+    } catch (err: any) {
+        if (err.code === "ENOENT") {
+            throw new Error(`Agent instructions file not found: ${resolvedPath} (from: ${filePath})`);
+        }
+        throw new Error(`Failed to load agent instructions file: ${resolvedPath} - ${err.message}`);
+    }
+}
+
+function renderTemplate(entry: FileCacheEntry, data: any): string {
+    if (entry.hasTemplateExpressions === false) {
+        return entry.content;
+    }
+
+    if (!entry.compiledTemplate) {
+        entry.hasTemplateExpressions = /\{\{/.test(entry.content);
+        if (!entry.hasTemplateExpressions) {
+            return entry.content;
+        }
+        entry.compiledTemplate = Handlebars.compile(entry.content);
+    }
+
+    return entry.compiledTemplate(data);
+}
+
+const TEXT_FILE_EXTENSIONS = [".md", ".txt", ".yaml", ".yml", ".xml", ".toml", ".ini", ".json", ".html", ".htm"];
+
+function isTextFilePath(value: string): boolean {
+    const trimmed = value.trimEnd().toLowerCase();
+    return TEXT_FILE_EXTENSIONS.some((ext) => trimmed.endsWith(ext));
+}
+
+/**
+ * Resolve an InstructionsReturn value to a plain string.
+ * @internal Used by FlinkAgent.toAgentProps()
+ */
+export async function resolveInstructionsReturn(result: InstructionsReturn, ctx: any, agentContext: any): Promise<string> {
+    if (typeof result === "string") {
+        if (isTextFilePath(result)) {
+            const entry = loadFile(result.trimEnd());
+            const templateData = { ctx, agentContext, user: agentContext?.user };
+            return renderTemplate(entry, templateData);
+        }
+        return result;
+    }
+
+    // { file, params? }
+    const { file, params } = result;
+    const entry = loadFile(file);
+    const templateData = { ...params, ctx, agentContext, user: agentContext?.user };
+    return renderTemplate(entry, templateData);
+}