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

package/src/ai/FlinkTool.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { FlinkContext } from "../FlinkContext";
+
+/**
+ * Standardized tool result format for better error handling
+ */
+export type ToolResult<T = any> =
+  | { success: true; data: T }
+  | { success: false; error: string; code?: string };
+
+export interface FlinkToolProps {
+  /**
+   * Unique identifier for the tool (kebab-case)
+   * Used to reference the tool in agents and for registration
+   * Example: "get-cars-tool", "search-users-tool"
+   */
+  id: string;
+
+  description: string; // For AI understanding
+  inputSchema: z.ZodType<any>; // Zod schema for validation + type inference
+  outputSchema?: z.ZodType<any>; // Optional output validation (validates the .data field)
+  permissions?:
+    | string
+    | string[]
+    | ((input: any, user?: any) => boolean | Promise<boolean>);
+}
+
+export interface FlinkTool<
+  Ctx extends FlinkContext,
+  Input = any,
+  Output = any,
+> {
+  (params: { input: Input; ctx: Ctx; user?: any }): Promise<ToolResult<Output>>;
+}
+
+export type FlinkToolFile = {
+  default: FlinkTool<any, any, any>;
+  Tool: FlinkToolProps;
+  __file?: string; // Set by compiler
+};

package/src/ai/LLMAdapter.ts

@@ -0,0 +1,96 @@
+/**
+ * Generic message format for LLM conversations
+ * Compatible with most LLM providers (Anthropic, OpenAI, etc.)
+ */
+export type LLMMessage =
+  | { role: "system"; content: string }
+  | { role: "user"; content: string | LLMContentBlock[] }
+  | { role: "assistant"; content: string | LLMContentBlock[] };
+
+export type LLMContentBlock =
+  | { type: "text"; text: string }
+  | { type: "tool_use"; id: string; name: string; input: any }
+  | { type: "tool_result"; tool_use_id: string; content: string; is_error?: boolean };
+
+/**
+ * Standard Flink tool schema format
+ * This is the format generated by ToolExecutor.getToolSchema()
+ * Adapters convert this to provider-specific formats
+ */
+export interface FlinkToolSchema {
+  /**
+   * Tool name (kebab-case identifier)
+   */
+  name: string;
+
+  /**
+   * Human-readable description for the LLM
+   */
+  description: string;
+
+  /**
+   * JSON Schema for tool input validation
+   * Generated from Zod schema via z.toJSONSchema()
+   */
+  inputSchema: Record<string, any>;
+}
+
+/**
+ * LLM Adapter interface for provider abstraction
+ * Enables support for multiple AI providers (Anthropic, OpenAI, Mistral, etc.)
+ *
+ * All adapters use streaming as the primary method since:
+ * - All modern LLM providers support streaming
+ * - Better user experience (time-to-first-token <500ms)
+ * - Prevents HTTP timeouts for long responses
+ * - FlinkAgent's lazy generator pattern allows both streaming and awaiting final result
+ *
+ * @template ToolSchema - The tool schema format accepted by this adapter (defaults to FlinkToolSchema)
+ */
+export interface LLMAdapter<ToolSchema = FlinkToolSchema> {
+  /**
+   * Optional debug flag to enable detailed logging
+   * When enabled, adapters will log:
+   * - Full request parameters sent to the LLM provider
+   * - Tool call decisions made by the LLM
+   * - Token usage and performance metrics
+   * - Error details and response metadata
+   *
+   * Useful for development and troubleshooting.
+   * Default: false
+   */
+  debug?: boolean;
+
+  /**
+   * Stream a completion with tool calling support
+   * Returns async generator for streaming responses
+   *
+   * Even if you want non-streaming UX, use this method and await the final result:
+   * ```typescript
+   * const response = agent.execute({ message: "Hello" });
+   * const result = await response.result; // Non-streaming consumption
+   * ```
+   */
+  stream(params: {
+    /**
+     * Instructions that define agent behavior and personality.
+     * Adapters should prepend this as a system message to the conversation.
+     * Following Vercel AI SDK pattern.
+     */
+    instructions: string;
+    messages: LLMMessage[];
+    tools: ToolSchema[];
+    maxTokens: number;
+    temperature: number;
+  }): AsyncGenerator<LLMStreamChunk>;
+}
+
+
+/**
+ * Streaming chunk types
+ */
+export type LLMStreamChunk =
+  | { type: "text"; delta: string }
+  | { type: "tool_call"; toolCall: { id: string; name: string; input: any } }
+  | { type: "usage"; usage: { inputTokens: number; outputTokens: number } }
+  | { type: "done"; stopReason: string };

package/src/ai/SubAgentExecutor.ts

@@ -0,0 +1,199 @@
+import { z } from "zod";
+import { FlinkContext } from "../FlinkContext";
+import { ToolResult } from "./FlinkTool";
+import { AgentExecuteResult, FlinkAgent, AgentExecuteContext } from "./FlinkAgent";
+import { log } from "../FlinkLog";
+import { generateShortId, toKebabCase, toSnakeCase } from "../utils";
+import { v4 as generateId } from "uuid";
+
+/**
+ * Special tool executor that wraps a sub-agent
+ * Automatically created for each agent reference in parent agent's `agents` array
+ */
+export class SubAgentExecutor<Ctx extends FlinkContext> {
+    private subAgentInstanceName: string;
+    private subAgentId: string;
+
+    constructor(
+        subAgentInstanceName: string,
+        private ctx: Ctx
+    ) {
+        this.subAgentInstanceName = subAgentInstanceName;
+        // Convert instance name to kebab-case for consistency with agent IDs
+        this.subAgentId = toKebabCase(subAgentInstanceName);
+    }
+
+    /**
+     * Execute the sub-agent with the given input
+     */
+    async execute(
+        input: any,
+        user?: any,
+        parentContext?: AgentExecuteContext, // NEW: parent agent context
+        userPermissions?: string[] // Resolved permissions from auth plugin
+    ): Promise<ToolResult<AgentExecuteResult>> {
+        try {
+            // Get the sub-agent from context
+            const agents = this.ctx.agents;
+            if (!agents) {
+                return {
+                    success: false,
+                    error: "Agents not available in context",
+                    code: "NO_AGENTS",
+                };
+            }
+
+            const subAgent: FlinkAgent<Ctx> = agents[this.subAgentInstanceName];
+            if (!subAgent) {
+                return {
+                    success: false,
+                    error: `Sub-agent ${this.subAgentInstanceName} not found`,
+                    code: "AGENT_NOT_FOUND",
+                };
+            }
+
+            // Bind user and permissions if provided
+            let boundAgent = subAgent;
+            if (user) {
+                boundAgent = boundAgent.withUser(user);
+            }
+            if (userPermissions) {
+                boundAgent = boundAgent.withPermissions(userPermissions);
+            }
+
+            // Determine conversation strategy
+            const strategy = subAgent.conversationStrategy || "inherit";
+
+            let conversationId: string | undefined;
+
+            if (strategy === "inherit") {
+                // Use parent's conversation ID
+                conversationId = parentContext?.conversationId;
+            } else if (strategy === "independent") {
+                // Create nested conversation
+                conversationId = parentContext?.conversationId
+                    ? `${parentContext.conversationId}:${this.subAgentInstanceName}:${generateShortId()}`
+                    : generateId();
+            } else {
+                // strategy === "none"
+                conversationId = undefined;
+            }
+
+            log.debug(
+                `Delegating to sub-agent ${this.subAgentInstanceName} from parent ${parentContext?.agentId || "unknown"}, ` +
+                    `strategy: "${strategy}", conversationId: ${conversationId || "none"}`
+            );
+
+            // Note: Input transformation happens in AgentRunner via transformSubAgentInput hook
+            // The input received here is already transformed if the parent agent has that hook
+
+            // Execute the sub-agent with conversation context
+            // Increment depth for sub-agent call to track recursion
+            const response = boundAgent.run({
+                message: input.query || input.message || JSON.stringify(input),
+                user,
+                userPermissions,
+                conversationId,
+                metadata: {
+                    ...input.metadata,
+                    parentConversationId: parentContext?.conversationId,
+                    parentAgentId: parentContext?.agentId,
+                    parentMetadata: parentContext?.metadata, // Preserve parent chain for error reporting
+                    isSubAgentCall: true,
+                    subAgentDepth: (parentContext?.subAgentDepth ?? 0) + 1,
+                },
+            });
+
+            const result = await response.result;
+
+            log.debug(`Sub-agent ${this.subAgentInstanceName} completed with ${result.stepsUsed} steps`);
+
+            return {
+                success: true,
+                data: result,
+            };
+        } catch (err: any) {
+            log.error(`Sub-agent ${this.subAgentInstanceName} execution failed:`, err.message);
+            return {
+                success: false,
+                error: `Sub-agent execution failed: ${err.message}`,
+                code: "SUB_AGENT_ERROR",
+            };
+        }
+    }
+
+    /**
+     * Generate tool schema for this sub-agent
+     * LLM sees this as a regular tool
+     */
+    getToolSchema(): any {
+        const agents = this.ctx.agents;
+
+        if (!agents?.[this.subAgentInstanceName]) {
+            throw new Error("Missing subagent: " + this.subAgentInstanceName);
+        }
+
+        const subAgent: FlinkAgent<Ctx> = agents?.[this.subAgentInstanceName];
+
+        const description = subAgent ? `Delegate to ${this.subAgentId}: ${subAgent.description}` : `Delegate to ${this.subAgentId}`;
+
+        // Simple schema - accepts a query string
+        const inputSchema = z.object({
+            query: z.string().describe("The question or task to send to the specialist agent"),
+        });
+
+        // Convert kebab-case ID to snake_case for tool name (ask_car_agent, not ask_car-agent)
+        const toolName = `ask_${toSnakeCase(this.subAgentId)}`;
+
+        return {
+            name: toolName,
+            description,
+            input_schema: (inputSchema as any).schema
+                ? (inputSchema as any).schema()
+                : {
+                      type: "object",
+                      properties: {
+                          query: { type: "string" },
+                      },
+                      required: ["query"],
+                  },
+        };
+    }
+
+    /**
+     * Format sub-agent result for AI consumption
+     */
+    formatResultForAI(result: ToolResult<AgentExecuteResult>): string {
+        if (result.success) {
+            const agentResult = result.data;
+            // Return the agent's final message as the tool result
+            return JSON.stringify({
+                answer: agentResult.message,
+                stepsUsed: agentResult.stepsUsed,
+                tokensUsed: (agentResult.usage?.inputTokens || 0) + (agentResult.usage?.outputTokens || 0),
+            });
+        } else {
+            return `Error: ${result.error}${result.code ? ` (${result.code})` : ""}`;
+        }
+    }
+
+    /**
+     * Check permissions - sub-agents handle their own permissions
+     */
+    async checkPermissions(_user?: any, _input?: any, _userPermissions?: string[]): Promise<boolean> {
+        // Sub-agents manage their own permissions
+        // The sub-agent's permissions will be checked when executed
+        return true;
+    }
+
+    /**
+     * Mark this as a sub-agent executor
+     */
+    isSubAgentExecutor(): boolean {
+        return true;
+    }
+
+    getSubAgentId(): string {
+        return this.subAgentId;
+    }
+}

package/src/ai/ToolExecutor.ts

@@ -0,0 +1,193 @@
+import { FlinkContext } from "../FlinkContext";
+import { log } from "../FlinkLog";
+import { FlinkTool, FlinkToolProps, ToolResult } from "./FlinkTool";
+import { FlinkToolSchema } from "./LLMAdapter";
+
+export class ToolExecutor<Ctx extends FlinkContext> {
+    constructor(
+        private toolProps: FlinkToolProps,
+        private toolFn: FlinkTool<Ctx, any, any>,
+        private ctx: Ctx
+    ) {}
+
+    async execute(input: any, user?: any, userPermissions?: string[]): Promise<ToolResult<any>> {
+        // 1. Permission check
+        if (this.toolProps.permissions) {
+            const hasPermission = await this.checkPermissionsInternal(input, user, userPermissions);
+            if (!hasPermission) {
+                return {
+                    success: false,
+                    error: `Permission denied for tool ${this.toolProps.id}`,
+                    code: "PERMISSION_DENIED",
+                };
+            }
+        }
+
+        // 2. Input validation
+        let validatedInput: any;
+        try {
+            validatedInput = this.toolProps.inputSchema.parse(input);
+        } catch (err: any) {
+            log.warn(`Tool ${this.toolProps.id} input validation failed:`, err.message);
+
+            // Format Zod validation errors for better LLM understanding
+            const errorDetails = this.formatValidationError(err, input);
+
+            return {
+                success: false,
+                error: `Invalid input for tool '${this.toolProps.id}': ${errorDetails}`,
+                code: "VALIDATION_ERROR",
+            };
+        }
+
+        // 3. Execute tool
+        log.debug(`Executing tool ${this.toolProps.id}`);
+        let result: ToolResult<any>;
+        try {
+            result = await this.toolFn({
+                input: validatedInput,
+                ctx: this.ctx,
+                user,
+            });
+        } catch (err: any) {
+            log.error(`Tool ${this.toolProps.id} threw error:`, err.message);
+            return {
+                success: false,
+                error: `Tool execution failed: ${err.message}`,
+                code: "EXECUTION_ERROR",
+            };
+        }
+
+        // 4. Handle error results
+        if (!result.success) {
+            log.warn(`Tool ${this.toolProps.id} returned error:`, result.error);
+            return result; // Return error result as-is
+        }
+
+        // 5. Output validation (if schema provided)
+        if (this.toolProps.outputSchema) {
+            try {
+                const validatedData = this.toolProps.outputSchema.parse(result.data);
+                return { success: true, data: validatedData };
+            } catch (err: any) {
+                log.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",
+                };
+            }
+        }
+
+        return result;
+    }
+
+    getToolSchema(): FlinkToolSchema {
+        // Use Zod 4's built-in z.toJSONSchema()
+        const zodSchema = this.toolProps.inputSchema;
+        const z = require("zod") as any;
+
+        return {
+            name: this.toolProps.id,
+            description: this.toolProps.description,
+            inputSchema: z.toJSONSchema ? z.toJSONSchema(zodSchema) : this.fallbackSchema(zodSchema),
+        };
+    }
+
+    /**
+     * Fallback schema generation if toJSONSchema is not available
+     */
+    private fallbackSchema(zodSchema: any): any {
+        // Try to use _def to extract basic schema info
+        log.warn(`Tool ${this.toolProps.id}: z.toJSONSchema() not available, using fallback schema generation`);
+        return {
+            type: "object",
+            properties: {},
+            required: [],
+        };
+    }
+
+    /**
+     * Get tool result for AI consumption
+     * Formats ToolResult into string for AI context
+     */
+    formatResultForAI(result: ToolResult<any>): string {
+        if (result.success) {
+            return JSON.stringify(result.data);
+        } else {
+            return `Error: ${result.error}${result.code ? ` (${result.code})` : ""}`;
+        }
+    }
+
+    /**
+     * Check if user has permission to use this tool
+     * Used by AgentRunner to filter tools before showing to LLM
+     *
+     * @param user - User object
+     * @param input - Tool input (for function-based permissions)
+     * @param userPermissions - Optional resolved permissions from auth plugin (preferred)
+     */
+    async checkPermissions(user?: any, input?: any, userPermissions?: string[]): Promise<boolean> {
+        const perms = this.toolProps.permissions;
+        if (!perms) return true;
+        if (typeof perms === "function") return await perms(input ?? {}, user);
+        if (!user) return false;
+
+        // Prefer userPermissions from request if available
+        const effectivePerms = userPermissions || user.permissions || [];
+
+        const requiredPerms = Array.isArray(perms) ? perms : [perms];
+        return requiredPerms.every((p) => effectivePerms.includes(p));
+    }
+
+    private async checkPermissionsInternal(input: any, user?: any, userPermissions?: string[]): Promise<boolean> {
+        return this.checkPermissions(user, input, userPermissions);
+    }
+
+    /**
+     * Format Zod validation errors into LLM-friendly error messages
+     * Provides specific guidance on what's missing or incorrect
+     */
+    private formatValidationError(err: any, receivedInput: any): string {
+        // Check if it's a Zod error with issues array
+        if (err.issues && Array.isArray(err.issues)) {
+            const issues = err.issues.map((issue: any) => {
+                const path = issue.path.join('.');
+                const field = path || 'input';
+
+                if (issue.code === 'invalid_type') {
+                    if (issue.received === 'undefined') {
+                        return `Missing required field '${field}' (expected ${issue.expected})`;
+                    }
+                    return `Field '${field}' has wrong type: expected ${issue.expected}, got ${issue.received}`;
+                }
+
+                if (issue.code === 'too_small') {
+                    if (issue.type === 'string') {
+                        return `Field '${field}' is too short (minimum ${issue.minimum} characters)`;
+                    }
+                    return `Field '${field}' is too small (minimum ${issue.minimum})`;
+                }
+
+                if (issue.code === 'too_big') {
+                    if (issue.type === 'string') {
+                        return `Field '${field}' is too long (maximum ${issue.maximum} characters)`;
+                    }
+                    return `Field '${field}' is too large (maximum ${issue.maximum})`;
+                }
+
+                // Generic fallback
+                return `${field}: ${issue.message}`;
+            });
+
+            const inputInfo = Object.keys(receivedInput || {}).length === 0
+                ? 'You provided an empty object {}.'
+                : `You provided: ${JSON.stringify(receivedInput)}`;
+
+            return `${issues.join('; ')}. ${inputInfo}`;
+        }
+
+        // Fallback for non-Zod errors
+        return err.message || 'Unknown validation error';
+    }
+}

package/src/ai/index.ts

@@ -0,0 +1,5 @@
+export * from "./FlinkTool";
+export * from "./FlinkAgent";
+export * from "./ToolExecutor";
+export * from "./AgentRunner";
+export * from "./LLMAdapter";

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

@@ -9,6 +9,10 @@ export * from "./FlinkPlugin";
 export * from "./FlinkJob";
 export * from "./auth/FlinkAuthUser";
 export * from "./auth/FlinkAuthPlugin";
+export * from "./ai/FlinkTool";
+export * from "./ai/FlinkAgent";
+export * from "./ai/ToolExecutor";
+export * from "./ai/LLMAdapter";
 
 // Re-export Express types for plugins and consumer apps
 // This ensures type consistency across the framework and plugins

package/src/utils.ts

@@ -59,6 +59,45 @@ export function getRepoInstanceName(fn: string) {
     return name.charAt(0).toLowerCase() + name.substr(1);
 }
 
+/**
+ * Convert PascalCase or camelCase to kebab-case
+ *
+ * Examples:
+ * - FooBarBaz → foo-bar-baz
+ * - CarAgent → car-agent
+ * - APIAgent → api-agent
+ * - HTMLParser → html-parser
+ * - IOManager → io-manager
+ *
+ * Handles:
+ * - Single uppercase followed by lowercase: CarAgent → car-agent
+ * - Multiple consecutive uppercase: APIAgent → api-agent
+ * - All caps: HTML → html
+ */
+export function toKebabCase(str: string): string {
+    return str
+        // Insert hyphen before uppercase letters that follow lowercase letters
+        // CarAgent → Car-Agent
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        // Insert hyphen before uppercase letter that follows uppercase and precedes lowercase
+        // APIAgent → API-Agent
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+        // Convert to lowercase
+        .toLowerCase();
+}
+
+/**
+ * Convert kebab-case to snake_case
+ *
+ * Examples:
+ * - car-agent → car_agent
+ * - api-agent → api_agent
+ * - html-parser → html_parser
+ */
+export function toSnakeCase(str: string): string {
+    return str.replace(/-/g, "_");
+}
+
 /**
  * Get http method from props or convention based on file name
  * if it starts with i.e "GetFoo"
@@ -177,3 +216,16 @@ export function formatValidationErrors(errors: any[] | null | undefined, data: a
 
     return formatted.join("\n");
 }
+
+/**
+ * Generate a short random ID for nested conversations
+ * Format: 8 character alphanumeric string (e.g., "a3b7c9d2")
+ */
+export function generateShortId(): string {
+    const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+    let result = "";
+    for (let i = 0; i < 8; i++) {
+        result += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return result;
+}