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

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.61",
+  "version": "2.0.0-alpha.63",
   "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/FlinkApp.undefinedResponse.spec.ts

@@ -0,0 +1,123 @@
+import { FlinkApp } from "../src/FlinkApp";
+import { FlinkContext } from "../src/FlinkContext";
+import { GetHandler, Handler, HttpMethod } from "../src/FlinkHttpHandler";
+
+const request = require("supertest");
+
+interface TestContext extends FlinkContext {}
+
+const resSchema = {
+    type: "object",
+    properties: {
+        id: { type: "string" },
+    },
+    required: ["id"],
+};
+
+describe("FlinkApp response validation when handler returns no data", () => {
+    let app: FlinkApp<TestContext>;
+
+    afterEach(async () => {
+        if (app && app.started) {
+            await app.stop();
+        }
+    });
+
+    it("should return 500 bad response when handler returns undefined data with a response schema", async () => {
+        const handler: GetHandler<TestContext, any> = async () => {
+            return { status: 200 } as any; // no data
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-undefined-data", port: 4200 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test", resSchema },
+        });
+
+        const response = await request(app.expressApp).get("/test");
+
+        expect(response.status).toBe(500);
+        expect(response.body.error.title).toBe("Bad response");
+        expect(response.body.error.detail).toContain("no data");
+    });
+
+    it("should NOT return 500 when handler returns status 204 with no data (even if schema is defined)", async () => {
+        const handler: Handler<TestContext, any, any> = async () => {
+            return { status: 204 } as any;
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-204-no-data", port: 4201 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.patch, path: "/test", resSchema },
+        });
+
+        const response = await request(app.expressApp).patch("/test");
+
+        expect(response.status).toBe(204);
+    });
+
+    it("should validate normally when handler returns valid data", async () => {
+        const handler: GetHandler<TestContext, any> = async () => {
+            return { data: { id: "abc-123" } };
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-valid-data", port: 4202 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test", resSchema },
+        });
+
+        const response = await request(app.expressApp).get("/test");
+
+        expect(response.status).toBe(200);
+        expect(response.body.data.id).toBe("abc-123");
+    });
+
+    it("should return 500 bad response when handler returns invalid data against schema", async () => {
+        const handler: GetHandler<TestContext, any> = async () => {
+            return { data: { wrongField: 123 } }; // missing required "id"
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-invalid-data", port: 4203 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test", resSchema },
+        });
+
+        const response = await request(app.expressApp).get("/test");
+
+        expect(response.status).toBe(500);
+        expect(response.body.error.title).toBe("Bad response");
+    });
+
+    it("should not crash the server when handler returns undefined data", async () => {
+        const handler: GetHandler<TestContext, any> = async () => {
+            return { status: 200 } as any;
+        };
+
+        app = new FlinkApp<TestContext>({ name: "test-no-crash", port: 4204 });
+        await app.start();
+
+        app.addHandler({
+            default: handler,
+            Route: { method: HttpMethod.get, path: "/test", resSchema },
+        });
+
+        // First request triggers the bad response
+        await request(app.expressApp).get("/test");
+
+        // Server should still be running and able to handle further requests
+        const second = await request(app.expressApp).get("/test");
+        expect(second.status).toBe(500); // still returns 500, but doesn't crash
+        expect(app.started).toBe(true);
+    });
+});

package/spec/FlinkJob.spec.ts

@@ -0,0 +1,95 @@
+import { FlinkApp, autoRegisteredJobs } from "../src/FlinkApp";
+import { FlinkContext } from "../src/FlinkContext";
+import { FlinkJobFile } from "../src/FlinkJob";
+
+interface TestContext extends FlinkContext {}
+
+describe("FlinkJob error handling", () => {
+    let app: FlinkApp<TestContext>;
+    let consoleErrorSpy: jasmine.Spy;
+
+    beforeEach(() => {
+        consoleErrorSpy = spyOn(console, "error");
+    });
+
+    afterEach(async () => {
+        autoRegisteredJobs.length = 0;
+        if (app?.started) {
+            await app.stop();
+        }
+    });
+
+    it("should catch and log errors from afterDelay 0ms jobs without crashing", async () => {
+        const job: FlinkJobFile = {
+            Job: { id: "failing-job-0ms", afterDelay: "0ms" },
+            default: async () => {
+                throw new Error("Job error 0ms");
+            },
+        };
+
+        autoRegisteredJobs.push(job);
+
+        app = new FlinkApp<TestContext>({ name: "test-job-errors-0ms", disableHttpServer: true });
+        await app.start();
+
+        await new Promise((resolve) => setTimeout(resolve, 50));
+
+        expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it("should catch and log errors from afterDelay jobs without crashing", async () => {
+        const job: FlinkJobFile = {
+            Job: { id: "failing-job-delay", afterDelay: "10ms" },
+            default: async () => {
+                throw new Error("Job error with delay");
+            },
+        };
+
+        autoRegisteredJobs.push(job);
+
+        app = new FlinkApp<TestContext>({ name: "test-job-errors-delay", disableHttpServer: true });
+        await app.start();
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it("should catch and log errors from interval jobs without crashing", async () => {
+        const job: FlinkJobFile = {
+            Job: { id: "failing-interval-job", interval: "10ms" },
+            default: async () => {
+                throw new Error("Interval job error");
+            },
+        };
+
+        autoRegisteredJobs.push(job);
+
+        app = new FlinkApp<TestContext>({ name: "test-job-errors-interval", disableHttpServer: true });
+        await app.start();
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        expect(consoleErrorSpy).toHaveBeenCalled();
+    });
+
+    it("should run afterDelay 0ms job exactly once", async () => {
+        let runCount = 0;
+
+        const job: FlinkJobFile = {
+            Job: { id: "once-job-0ms", afterDelay: "0ms" },
+            default: async () => {
+                runCount++;
+            },
+        };
+
+        autoRegisteredJobs.push(job);
+
+        app = new FlinkApp<TestContext>({ name: "test-job-once-0ms", disableHttpServer: true });
+        await app.start();
+
+        await new Promise((resolve) => setTimeout(resolve, 100));
+
+        expect(runCount).toBe(1);
+    });
+});

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 = [];
 }