@flink-app/flink 0.14.3 → 2.0.0-alpha.100

package/src/ai/agentInstructions.ts

@@ -0,0 +1,245 @@
+import * as fs from "fs";
+import * as path from "path";
+import Handlebars from "handlebars";
+import { FlinkContext } from "../FlinkContext";
+import { InstructionsCallback, AgentExecuteContext } from "./FlinkAgent";
+
+/**
+ * File cache structure: stores file content and modification time
+ */
+interface FileCacheEntry {
+    content: string;
+    mtime: number;
+    compiledTemplate?: Handlebars.TemplateDelegate;
+    hasTemplateExpressions?: boolean;
+}
+
+/**
+ * In-memory file cache (per-process, not persistent)
+ */
+const fileCache = new Map<string, FileCacheEntry>();
+
+/**
+ * Get caller's file location using stack trace API
+ * This enables agent-relative path resolution for ./ and ../ prefixes
+ *
+ * Walks the stack to find the first frame outside this file,
+ * which is the agent class that called agentInstructions().
+ */
+function getCallerFilePath(): string {
+    const originalPrepareStackTrace = Error.prepareStackTrace;
+    Error.prepareStackTrace = (_, stack) => stack;
+    const stack = new Error().stack as unknown as NodeJS.CallSite[];
+    Error.prepareStackTrace = originalPrepareStackTrace;
+
+    // Find first frame outside this file (skips getCallerFilePath, resolveFilePath, agentInstructions)
+    const thisFile = stack[0]?.getFileName();
+    for (let i = 1; i < stack.length; i++) {
+        const fileName = stack[i]?.getFileName();
+        if (fileName && fileName !== thisFile) {
+            return fileName;
+        }
+    }
+
+    throw new Error("Could not determine caller file location for agent-relative path");
+}
+
+/**
+ * Resolve file path based on prefix:
+ * - ./ or ../ = agent-relative (using caller's location)
+ * - otherwise = project root-relative
+ */
+function resolveFilePath(filePath: string): string {
+    // Always try project root-relative first (most intuitive for users)
+    const cwdResolved = path.join(process.cwd(), filePath);
+    if (fs.existsSync(cwdResolved)) {
+        return cwdResolved;
+    }
+
+    if (filePath.startsWith("./") || filePath.startsWith("../")) {
+        // Agent-relative: get caller's file location via stack trace
+        const callerFile = getCallerFilePath();
+        const resolved = path.resolve(path.dirname(callerFile), filePath);
+
+        if (fs.existsSync(resolved)) {
+            return resolved;
+        }
+
+        // At runtime, callerFile points to compiled JS in dist/.
+        // Non-JS assets (e.g. .md instruction files) live in the source tree,
+        // so try the equivalent source path with dist/ removed.
+        const distIndex = resolved.lastIndexOf(path.sep + "dist" + path.sep);
+        if (distIndex !== -1) {
+            const sourcePath = resolved.substring(0, distIndex) + resolved.substring(distIndex + 5); // remove "/dist"
+            if (fs.existsSync(sourcePath)) {
+                return sourcePath;
+            }
+        }
+
+        return resolved;
+    } else {
+        // Project root-relative
+        return cwdResolved;
+    }
+}
+
+/**
+ * Load file contents with smart caching
+ * Cache is invalidated when file modification time changes
+ */
+function loadFile(resolvedPath: string, originalPath: string): FileCacheEntry {
+    try {
+        const stats = fs.statSync(resolvedPath);
+        const mtime = stats.mtimeMs;
+
+        // Check cache
+        const cached = fileCache.get(resolvedPath);
+        if (cached && cached.mtime === mtime) {
+            return cached;
+        }
+
+        // Read file and update cache (clear compiled template on file change)
+        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: ${originalPath})`);
+        }
+        throw new Error(`Failed to load agent instructions file: ${resolvedPath} - ${err.message}`);
+    }
+}
+
+/**
+ * Render template using Handlebars with compiled template caching.
+ * Skips Handlebars entirely when content has no template expressions.
+ */
+function renderTemplate(cached: FileCacheEntry, data: any, filePath: string): string {
+    if (cached.hasTemplateExpressions === false) {
+        return cached.content;
+    }
+
+    try {
+        if (!cached.compiledTemplate) {
+            cached.hasTemplateExpressions = /\{\{/.test(cached.content);
+            if (!cached.hasTemplateExpressions) {
+                return cached.content;
+            }
+            cached.compiledTemplate = Handlebars.compile(cached.content);
+        }
+        return cached.compiledTemplate(data);
+    } catch (err: any) {
+        throw new Error(`Failed to render template in ${filePath}: ${err.message}`);
+    }
+}
+
+/**
+ * Load agent instructions from external files with template variable support
+ *
+ * Supports multiple file types: .md, .yaml, .txt, etc. (loaded as plain text)
+ *
+ * ## Path Resolution
+ *
+ * - `./` or `../` prefix: Agent-relative path (based on caller's file location)
+ * - Otherwise: Project root-relative path
+ *
+ * ## Template Variables
+ *
+ * Uses Handlebars templating with automatic context helpers:
+ * - `ctx`: Full FlinkContext
+ * - `agentContext`: AgentExecuteContext
+ * - `user`: Shortcut to agentContext.user
+ * - Custom variables from static object or callback
+ *
+ * ## Caching
+ *
+ * Files are cached in-memory and reloaded only when modification time changes
+ *
+ * @example Agent-relative path with static variables
+ * ```typescript
+ * export default class CarAgent extends FlinkAgent<AppCtx> {
+ *   id = "car-agent";
+ *   instructions = agentInstructions("./instructions/car-agent.md");
+ *   tools = [SearchCarsTool];
+ * }
+ * ```
+ *
+ * @example Dynamic variables with callback
+ * ```typescript
+ * export default class SupportAgent extends FlinkAgent<AppCtx> {
+ *   id = "support-agent";
+ *   instructions = agentInstructions(
+ *     "./instructions/support-agent.md",
+ *     (ctx, agentContext) => ({
+ *       isBusinessHours: new Date().getHours() >= 9 && new Date().getHours() < 17,
+ *       customerTier: agentContext.user?.tier || "standard",
+ *     })
+ *   );
+ *   tools = [CreateTicketTool];
+ * }
+ * ```
+ *
+ * @example Template file (instructions/support-agent.md)
+ * ```markdown
+ * You are a customer support agent.
+ *
+ * Customer: {{user.name}} ({{customerTier}})
+ * {{#if user.isPremium}}
+ * ⭐ VIP CUSTOMER - Provide white-glove service!
+ * {{/if}}
+ *
+ * {{#unless isBusinessHours}}
+ * NOTE: Outside business hours. Suggest emergency contact.
+ * {{/unless}}
+ * ```
+ *
+ * @param filePath - Path to instructions file (./ for agent-relative, otherwise project root)
+ * @param variables - Static object or callback returning template variables
+ * @returns InstructionsCallback compatible with FlinkAgent.instructions property
+ */
+export 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> {
+    // Resolve path once at definition time for early validation
+    const resolvedPath = resolveFilePath(filePath);
+
+    // Return callback that will be invoked by FlinkAgent
+    return async (ctx: Ctx, agentContext: AgentExecuteContext): Promise<string> => {
+        // Load file (uses cache if available and mtime unchanged)
+        const cached = loadFile(resolvedPath, filePath);
+
+        // Skip template processing entirely when no expressions exist
+        if (cached.hasTemplateExpressions === false) {
+            return cached.content;
+        }
+
+        // Resolve variables (static or callback)
+        let vars: Record<string, any> = {};
+        if (variables) {
+            if (typeof variables === "function") {
+                vars = await Promise.resolve(variables(ctx, agentContext));
+            } else {
+                vars = variables;
+            }
+        }
+
+        // Merge with automatic context helpers
+        const templateData = {
+            ...vars,
+            ctx,
+            agentContext,
+            user: agentContext.user,
+        };
+
+        // Render template (compiles and caches Handlebars template on first call)
+        return renderTemplate(cached, templateData, resolvedPath);
+    };
+}
+
+// Re-export types for convenience
+export type { InstructionsCallback, AgentExecuteContext, InstructionsReturn } from "./FlinkAgent";

package/src/ai/index.ts

@@ -0,0 +1,8 @@
+export * from "./FlinkTool";
+export * from "./FlinkAgent";
+export * from "./ConversationAgent";
+export * from "./InMemoryConversationAgent";
+export * from "./ToolExecutor";
+export * from "./AgentRunner";
+export * from "./LLMAdapter";
+export { agentInstructions } from "./agentInstructions";

package/src/ai/instructionFileLoader.ts

@@ -0,0 +1,156 @@
+import * as fs from "fs";
+import * as path from "path";
+import Handlebars from "handlebars";
+
+// Enable {{{{raw}}}}...{{{{/raw}}}} blocks to pass content through unprocessed.
+// Without this, content inside raw blocks is silently dropped.
+Handlebars.registerHelper("raw", function (this: any, options: any) {
+    return options.fn(this);
+});
+
+/**
+ * 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;
+    resolvedContent: string;
+    mtime: number;
+    compiledTemplate?: Handlebars.TemplateDelegate;
+    hasTemplateExpressions?: boolean;
+}
+
+const fileCache = new Map<string, FileCacheEntry>();
+
+const IMPORT_REGEX = /\{\{\s*import\s+["']([^"']+)['"]\s*\}\}/g;
+
+function resolveImports(content: string, currentDir: string, visited: Set<string> = new Set()): string {
+    return content.replace(IMPORT_REGEX, (match, importPath) => {
+        const resolved = path.resolve(currentDir, importPath);
+        if (visited.has(resolved)) {
+            throw new Error(`Circular import detected: ${resolved}`);
+        }
+        const nextVisited = new Set(visited);
+        nextVisited.add(resolved);
+        try {
+            const importedContent = fs.readFileSync(resolved, "utf-8");
+            return resolveImports(importedContent, path.dirname(resolved), nextVisited);
+        } catch (err: any) {
+            if (err.code === "ENOENT") {
+                throw new Error(`Imported markdown file not found: ${resolved} (imported from: ${currentDir})`);
+            }
+            throw err;
+        }
+    });
+}
+
+/**
+ * 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 resolvedContent = resolveImports(content, path.dirname(resolvedPath));
+        const entry: FileCacheEntry = { content, resolvedContent, 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.resolvedContent;
+    }
+
+    if (!entry.compiledTemplate) {
+        entry.hasTemplateExpressions = /\{\{/.test(entry.resolvedContent);
+        if (!entry.hasTemplateExpressions) {
+            return entry.resolvedContent;
+        }
+        entry.compiledTemplate = Handlebars.compile(entry.resolvedContent);
+    }
+
+    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);
+}

package/src/auth/FlinkAuthPlugin.ts

@@ -3,7 +3,8 @@ import { FlinkRequest } from "../FlinkHttpHandler";
 export interface FlinkAuthPlugin {
   authenticateRequest: (
     req: FlinkRequest,
-    permissions: string | string[]
+    permissions: string | string[],
+    ctx?: any
   ) => Promise<boolean>;
   createToken: (payload: any, roles: string[]) => Promise<string>;
 }

package/src/handlers/StreamWriterFactory.ts

@@ -0,0 +1,84 @@
+import { Response } from "express";
+import { StreamWriter, StreamFormat } from "../FlinkHttpHandler";
+import { log } from "../FlinkLog";
+
+/**
+ * Factory for creating StreamWriter instances for SSE and NDJSON streaming.
+ *
+ * Handles HTTP headers, connection lifecycle, and format-specific serialization.
+ */
+export class StreamWriterFactory {
+    /**
+     * Create a StreamWriter for the given format.
+     *
+     * Sets appropriate HTTP headers and manages the stream lifecycle including
+     * client disconnect detection.
+     *
+     * @param res - Express response object
+     * @param format - Stream format (sse or ndjson)
+     * @returns StreamWriter instance for writing data to the stream
+     */
+    static create<T = any>(res: Response, format: StreamFormat): StreamWriter<T> {
+        // Set appropriate headers based on format
+        if (format === "sse") {
+            res.setHeader("Content-Type", "text/event-stream");
+            res.setHeader("Cache-Control", "no-cache");
+            res.setHeader("Connection", "keep-alive");
+            res.flushHeaders();
+        } else if (format === "ndjson") {
+            res.setHeader("Content-Type", "application/x-ndjson");
+            res.setHeader("Cache-Control", "no-cache");
+            res.flushHeaders();
+        }
+
+        let isOpen = true;
+
+        // Detect client disconnect
+        res.on("close", () => {
+            isOpen = false;
+        });
+
+        return {
+            write: (data: T) => {
+                if (!isOpen) return;
+
+                try {
+                    const json = JSON.stringify(data);
+
+                    if (format === "sse") {
+                        res.write(`data: ${json}\n\n`);
+                    } else if (format === "ndjson") {
+                        res.write(`${json}\n`);
+                    }
+                } catch (err) {
+                    log.error("StreamWriter serialization error:", { error: err });
+                    isOpen = false;
+                }
+            },
+
+            error: (error: Error | string) => {
+                if (!isOpen) return;
+
+                const errorMessage = typeof error === "string" ? error : error.message;
+
+                if (format === "sse") {
+                    res.write(`event: error\ndata: ${JSON.stringify({ error: errorMessage })}\n\n`);
+                } else if (format === "ndjson") {
+                    res.write(`${JSON.stringify({ error: errorMessage })}\n`);
+                }
+
+                res.end();
+                isOpen = false;
+            },
+
+            end: () => {
+                if (isOpen) {
+                    res.end();
+                    isOpen = false;
+                }
+            },
+
+            isOpen: () => isOpen,
+        };
+    }
+}

package/src/index.ts

@@ -1,14 +1,28 @@
 export * from "./FlinkLog";
+export * from "./FlinkLogFactory";
 export * from "./FlinkApp";
+export * from "./utils/loadFlinkConfig";
 export * from "./FlinkHttpHandler";
 export * from "./FlinkContext";
 export * from "./FlinkRepo";
 export * from "./FlinkResponse";
+export * from "./FlinkRequestContext";
 export * from "./FlinkErrors";
 export * from "./FlinkPlugin";
 export * from "./FlinkJob";
+export * from "./FlinkService";
+export { LeaderElection } from "./LeaderElection";
+export type { LeaderElectionOptions } from "./LeaderElection";
 export * from "./auth/FlinkAuthUser";
 export * from "./auth/FlinkAuthPlugin";
+export * from "./ai/FlinkTool";
+export * from "./ai/FlinkAgent";
+export * from "./ai/ConversationAgent";
+export * from "./ai/InMemoryConversationAgent";
+export * from "./ai/ToolExecutor";
+export * from "./ai/LLMAdapter";
+export { agentInstructions } from "./ai/agentInstructions";
+export { loadPluginSchemas } from "./loadPluginSchemas";
 
 // Re-export Express types for plugins and consumer apps
 // This ensures type consistency across the framework and plugins

package/src/loadPluginSchemas.ts

@@ -0,0 +1,141 @@
+import * as fs from "fs";
+import * as path from "path";
+
+interface SchemaManifest {
+    version?: string;
+    schemas?: Record<string, any>;
+    definitions?: Record<string, any>;
+    handlers: Record<
+        string,
+        {
+            reqSchemaName?: string;
+            resSchemaName?: string;
+            queryMetadata?: any[];
+            paramsMetadata?: any[];
+            assumedMethod?: string;
+        }
+    >;
+    tools: Record<string, any>;
+}
+
+/**
+ * Prefix a schema $id or $ref value with the plugin namespace.
+ */
+function prefixId(pluginId: string, id: string): string {
+    return `${pluginId}::${id}`;
+}
+
+/**
+ * Deep-clone a schema and prefix all $id and $ref values with the plugin namespace.
+ * Only prefixes $ref values that refer to schemas within this plugin's universe.
+ */
+function prefixSchema(pluginId: string, schema: any, knownIds: Set<string>): any {
+    if (!schema || typeof schema !== "object") return schema;
+
+    if (Array.isArray(schema)) {
+        return schema.map((item) => prefixSchema(pluginId, item, knownIds));
+    }
+
+    const result: any = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === "$id" && typeof value === "string") {
+            result[key] = prefixId(pluginId, value);
+        } else if (key === "$ref" && typeof value === "string") {
+            // Only prefix refs that point to known plugin schemas
+            if (knownIds.has(value)) {
+                result[key] = prefixId(pluginId, value);
+            } else {
+                result[key] = value;
+            }
+        } else if (typeof value === "object") {
+            result[key] = prefixSchema(pluginId, value, knownIds);
+        } else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+
+/**
+ * Load a plugin's schema manifest and provide helpers for getting
+ * namespaced schemas suitable for use with `app.registerSchemas()` and `addHandler()`.
+ *
+ * @param packageName The npm package name (e.g., "@flink-app/generic-auth-plugin").
+ *                    The package's `dist/.flink/schema-manifest.json` will be loaded.
+ * @returns Object with helper methods for retrieving prefixed schemas.
+ */
+export function loadPluginSchemas(packageName: string) {
+    let manifest: SchemaManifest;
+
+    // Resolve the package directory
+    const packageDir = path.dirname(require.resolve(path.join(packageName, "package.json")));
+    const manifestPath = path.join(packageDir, "dist/.flink/schema-manifest.json");
+
+    if (!fs.existsSync(manifestPath)) {
+        // No manifest — return empty helpers
+        manifest = { handlers: {}, tools: {} };
+    } else {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    }
+
+    // Collect all known schema $ids for ref resolution
+    const schemas = manifest.schemas || manifest.definitions || {};
+    const knownIds = new Set<string>();
+    for (const schema of Object.values(schemas)) {
+        if (schema && typeof schema === "object" && schema.$id) {
+            knownIds.add(schema.$id);
+        }
+    }
+
+    return {
+        /**
+         * Get prefixed req/res schemas for a specific handler file path.
+         *
+         * @param pluginId Plugin instance ID used as namespace prefix
+         * @param filePath Handler file path as it appears in the manifest (e.g., "src/handlers/UserLogin.ts")
+         */
+        getHandlerSchemas(
+            pluginId: string,
+            filePath: string
+        ): { reqSchema?: object; resSchema?: object } {
+            const metadata = manifest.handlers[filePath];
+            if (!metadata) return {};
+
+            const result: { reqSchema?: object; resSchema?: object } = {};
+
+            if (metadata.reqSchemaName && schemas[metadata.reqSchemaName]) {
+                result.reqSchema = prefixSchema(pluginId, schemas[metadata.reqSchemaName], knownIds);
+            }
+            if (metadata.resSchemaName && schemas[metadata.resSchemaName]) {
+                result.resSchema = prefixSchema(pluginId, schemas[metadata.resSchemaName], knownIds);
+            }
+
+            return result;
+        },
+
+        /**
+         * Get all schemas from the plugin's manifest, prefixed with the plugin namespace.
+         * Pass the result to `app.registerSchemas()` for $ref resolution.
+         *
+         * @param pluginId Plugin instance ID used as namespace prefix
+         */
+        getAllSchemas(pluginId: string): Record<string, any> {
+            const prefixed: Record<string, any> = {};
+            for (const [name, schema] of Object.entries(schemas)) {
+                if (schema && typeof schema === "object") {
+                    const prefixedSchema = prefixSchema(pluginId, schema, knownIds);
+                    const prefixedName = prefixId(pluginId, name);
+                    prefixed[prefixedName] = prefixedSchema;
+                }
+            }
+            return prefixed;
+        },
+
+        /**
+         * Get the raw manifest (for inspection/debugging).
+         */
+        getManifest(): SchemaManifest {
+            return manifest;
+        },
+    };
+}