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

package/src/FlinkApp.ts

@@ -790,20 +790,32 @@ export class FlinkApp<C extends FlinkContext> {
                 }
 
                 if (validateRes && !isError(handlerRes)) {
-                    const valid = validateRes(JSON.parse(JSON.stringify(handlerRes.data)));
-
-                    if (!valid) {
-                        const formattedErrors = formatValidationErrors(validateRes.errors, handlerRes.data);
-                        log.warn(`[${req.reqId}] ${methodAndRoute}: Bad response\n${formattedErrors}`);
-
-                        return res.status(500).json({
-                            status: 500,
-                            error: {
-                                id: v4(),
-                                title: "Bad response",
-                                detail: formattedErrors,
-                            },
-                        });
+                    if (handlerRes.data === undefined) {
+                        if (handlerRes.status !== 204) {
+                            const detail =
+                                "Response schema is defined but handler returned no data";
+                            log.warn(`[${req.reqId}] ${methodAndRoute}: Bad response - ${detail}`);
+                            return res.status(500).json({
+                                status: 500,
+                                error: { id: v4(), title: "Bad response", detail },
+                            });
+                        }
+                    } else {
+                        const valid = validateRes(JSON.parse(JSON.stringify(handlerRes.data)));
+
+                        if (!valid) {
+                            const formattedErrors = formatValidationErrors(validateRes.errors, handlerRes.data);
+                            log.warn(`[${req.reqId}] ${methodAndRoute}: Bad response\n${formattedErrors}`);
+
+                            return res.status(500).json({
+                                status: 500,
+                                error: {
+                                    id: v4(),
+                                    title: "Bad response",
+                                    detail: formattedErrors,
+                                },
+                            });
+                        }
                     }
                 }
 
@@ -1198,18 +1210,30 @@ export class FlinkApp<C extends FlinkContext> {
 
                 this.scheduler.addSimpleIntervalJob(job);
             } else if (jobProps.afterDelay !== undefined) {
-                const job = new SimpleIntervalJob(
-                    {
-                        milliseconds: ms(jobProps.afterDelay),
-                        runImmediately: false,
-                    },
-                    task,
-                    {
-                        id: jobProps.id,
-                        preventOverrun: jobProps.singleton,
-                    }
-                );
-                this.scheduler.addSimpleIntervalJob(job);
+                const delayMs = ms(jobProps.afterDelay);
+                if (delayMs === 0) {
+                    setImmediate(async () => {
+                        try {
+                            await jobFn({ ctx: this.ctx });
+                        } catch (err) {
+                            log.error(`Job ${jobProps.id} threw unhandled exception ${err}`);
+                            console.error(err);
+                        }
+                    });
+                } else {
+                    const job = new SimpleIntervalJob(
+                        {
+                            milliseconds: delayMs,
+                            runImmediately: false,
+                        },
+                        task,
+                        {
+                            id: jobProps.id,
+                            preventOverrun: jobProps.singleton,
+                        }
+                    );
+                    this.scheduler.addSimpleIntervalJob(job);
+                }
             } else {
                 log.error(`Cannot register job ${jobProps.id} - no cron, interval or once set in ${__file}`);
                 continue;
@@ -1270,11 +1294,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);
+}