@flink-app/flink 2.0.0-alpha.61 → 2.0.0-alpha.63

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @flink-app/flink
 
+## 2.0.0-alpha.63
+
+### Patch Changes
+
+-   810df2c: Fix FlinkJob afterDelay: "0ms" running in a tight loop instead of once. Zero-delay jobs now run immediately via setImmediate (exactly once) rather than being registered with a 0ms scheduler interval. Also adds specs covering uncaught exception handling for all job scheduling modes.
+-   8dd0752: fix: prevent server crash when handler returns no data with a response schema defined
+
+    When a PATCH (or any) handler returned `{ status: 204 }` without a `data` field,
+    `JSON.stringify(undefined)` returned the JS value `undefined`, causing
+    `JSON.parse(undefined)` to throw a `SyntaxError` that crashed the entire server process.
+
+    New behaviour:
+
+    -   Status 204 + no data → skip validation silently (intentional no-content response)
+    -   Non-204 status + no data + response schema defined → return 500 bad response with a
+        descriptive error message (surfaces the developer mistake without crashing the server)
+    -   Data present → validate against schema as before
+
+## 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

package/dist/src/FlinkApp.js

@@ -423,7 +423,7 @@ var FlinkApp = /** @class */ (function () {
                 }
             }
             this.expressApp[method](routeProps.path, function (req, res) { return __awaiter(_this, void 0, void 0, function () {
-                var valid, formattedErrors, data, normalizedQuery, _i, _a, _b, key, value, stream, handlerRes, flinkReq_1, err_1, errorResponse, result, valid, formattedErrors;
+                var valid, formattedErrors, data, normalizedQuery, _i, _a, _b, key, value, stream, handlerRes, flinkReq_1, err_1, errorResponse, result, detail, valid, formattedErrors;
                 var _this = this;
                 return __generator(this, function (_c) {
                     switch (_c.label) {
@@ -570,18 +570,30 @@ var FlinkApp = /** @class */ (function () {
                                 return [2 /*return*/, res.status(204).send()];
                             }
                             if (validateRes_1 && !(0, utils_1.isError)(handlerRes)) {
-                                valid = validateRes_1(JSON.parse(JSON.stringify(handlerRes.data)));
-                                if (!valid) {
-                                    formattedErrors = (0, utils_1.formatValidationErrors)(validateRes_1.errors, handlerRes.data);
-                                    FlinkLog_1.log.warn("[".concat(req.reqId, "] ").concat(methodAndRoute_1, ": Bad response\n").concat(formattedErrors));
-                                    return [2 /*return*/, res.status(500).json({
-                                            status: 500,
-                                            error: {
-                                                id: (0, uuid_1.v4)(),
-                                                title: "Bad response",
-                                                detail: formattedErrors,
-                                            },
-                                        })];
+                                if (handlerRes.data === undefined) {
+                                    if (handlerRes.status !== 204) {
+                                        detail = "Response schema is defined but handler returned no data";
+                                        FlinkLog_1.log.warn("[".concat(req.reqId, "] ").concat(methodAndRoute_1, ": Bad response - ").concat(detail));
+                                        return [2 /*return*/, res.status(500).json({
+                                                status: 500,
+                                                error: { id: (0, uuid_1.v4)(), title: "Bad response", detail: detail },
+                                            })];
+                                    }
+                                }
+                                else {
+                                    valid = validateRes_1(JSON.parse(JSON.stringify(handlerRes.data)));
+                                    if (!valid) {
+                                        formattedErrors = (0, utils_1.formatValidationErrors)(validateRes_1.errors, handlerRes.data);
+                                        FlinkLog_1.log.warn("[".concat(req.reqId, "] ").concat(methodAndRoute_1, ": Bad response\n").concat(formattedErrors));
+                                        return [2 /*return*/, res.status(500).json({
+                                                status: 500,
+                                                error: {
+                                                    id: (0, uuid_1.v4)(),
+                                                    title: "Bad response",
+                                                    detail: formattedErrors,
+                                                },
+                                            })];
+                                    }
                                 }
                             }
                             res.set(handlerRes.headers);
@@ -901,14 +913,38 @@ var FlinkApp = /** @class */ (function () {
                         this_1.scheduler.addSimpleIntervalJob(job);
                     }
                     else if (jobProps.afterDelay !== undefined) {
-                        var job = new toad_scheduler_1.SimpleIntervalJob({
-                            milliseconds: (0, ms_1.default)(jobProps.afterDelay),
-                            runImmediately: false,
-                        }, task, {
-                            id: jobProps.id,
-                            preventOverrun: jobProps.singleton,
-                        });
-                        this_1.scheduler.addSimpleIntervalJob(job);
+                        var delayMs = (0, ms_1.default)(jobProps.afterDelay);
+                        if (delayMs === 0) {
+                            setImmediate(function () { return __awaiter(_this, void 0, void 0, function () {
+                                var err_2;
+                                return __generator(this, function (_a) {
+                                    switch (_a.label) {
+                                        case 0:
+                                            _a.trys.push([0, 2, , 3]);
+                                            return [4 /*yield*/, jobFn({ ctx: this.ctx })];
+                                        case 1:
+                                            _a.sent();
+                                            return [3 /*break*/, 3];
+                                        case 2:
+                                            err_2 = _a.sent();
+                                            FlinkLog_1.log.error("Job ".concat(jobProps.id, " threw unhandled exception ").concat(err_2));
+                                            console.error(err_2);
+                                            return [3 /*break*/, 3];
+                                        case 3: return [2 /*return*/];
+                                    }
+                                });
+                            }); });
+                        }
+                        else {
+                            var job = new toad_scheduler_1.SimpleIntervalJob({
+                                milliseconds: delayMs,
+                                runImmediately: false,
+                            }, task, {
+                                id: jobProps.id,
+                                preventOverrun: jobProps.singleton,
+                            });
+                            this_1.scheduler.addSimpleIntervalJob(job);
+                        }
                     }
                     else {
                         FlinkLog_1.log.error("Cannot register job ".concat(jobProps.id, " - no cron, interval or once set in ").concat(__file));
@@ -931,7 +967,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 +1004,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, ")"));
                 }
@@ -1110,7 +1147,7 @@ var FlinkApp = /** @class */ (function () {
      */
     FlinkApp.prototype.initDb = function () {
         return __awaiter(this, void 0, void 0, function () {
-            var client, err_2;
+            var client, err_3;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
@@ -1126,8 +1163,8 @@ var FlinkApp = /** @class */ (function () {
                         this.dbClient = client;
                         return [3 /*break*/, 4];
                     case 3:
-                        err_2 = _a.sent();
-                        FlinkLog_1.log.error("Failed to connect to db: " + err_2);
+                        err_3 = _a.sent();
+                        FlinkLog_1.log.error("Failed to connect to db: " + err_3);
                         process.exit(1);
                         return [3 /*break*/, 4];
                     case 4:
@@ -1146,7 +1183,7 @@ var FlinkApp = /** @class */ (function () {
      */
     FlinkApp.prototype.initPluginDb = function (plugin) {
         return __awaiter(this, void 0, void 0, function () {
-            var client, err_3;
+            var client, err_4;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
@@ -1173,8 +1210,8 @@ var FlinkApp = /** @class */ (function () {
                         client = _a.sent();
                         return [2 /*return*/, client.db()];
                     case 4:
-                        err_3 = _a.sent();
-                        FlinkLog_1.log.error("Failed to connect to db defined in plugin '".concat(plugin.id, "': ") + err_3);
+                        err_4 = _a.sent();
+                        FlinkLog_1.log.error("Failed to connect to db defined in plugin '".concat(plugin.id, "': ") + err_4);
                         return [3 /*break*/, 5];
                     case 5: return [2 /*return*/];
                 }

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>;