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

package/src/ai/ConversationAgent.ts

@@ -0,0 +1,413 @@
+import { FlinkContext } from "../FlinkContext";
+import { FlinkLogFactory } from "../FlinkLogFactory";
+import { AgentExecuteContext, AgentExecuteInput, AgentExecuteResult, AgentFinishContext, FlinkAgent, Message } from "./FlinkAgent";
+
+export const logger = FlinkLogFactory.createLogger("flink.ai.conversation-agent");
+
+/**
+ * Storage message format - flexible structure for conversation persistence.
+ *
+ * Supports text content, tool calls, and tool results in a single message.
+ * More flexible than FlinkAgent's union Message type for storage purposes.
+ */
+export interface StorageMessage {
+    role: "user" | "assistant" | "system" | "tool";
+    content?: string;
+    toolCalls?: Array<{
+        id: string;
+        name: string;
+        input: any;
+    }>;
+    toolResults?: Array<{
+        id: string;
+        result: any;
+    }>;
+}
+
+/**
+ * Conversation data structure for persistent storage.
+ *
+ * @property messages - Array of conversation messages in the storage format
+ * @property providerMetadata - Provider-specific metadata (e.g., OpenAI's responseId, instructionsHash)
+ */
+export interface ConversationData {
+    messages: StorageMessage[];
+    providerMetadata?: Record<string, any>;
+}
+
+/**
+ * Abstract base class for agents with automatic conversation persistence.
+ *
+ * ConversationAgent eliminates boilerplate by automatically:
+ * - Loading conversation history before agent execution
+ * - Saving messages and provider metadata after execution
+ * - Enabling LLM provider optimizations (e.g., OpenAI's previousResponseId for 40-80% cost savings)
+ *
+ * ## Benefits
+ *
+ * - **Type Safety**: Abstract methods enforce consistent storage implementation
+ * - **Backend Flexibility**: Works with MongoDB, Redis, in-memory, or any storage backend
+ * - **Sub-Agent Aware**: Automatically skips persistence for sub-agent calls (parent handles it)
+ * - **Metadata Tracking**: Preserves provider metadata for debugging and future extensibility
+ *
+ * ## Usage Examples
+ *
+ * ### MongoDB Storage
+ * ```typescript
+ * export default class CarAgent extends ConversationAgent<AppContext> {
+ *     id = "car-agent";
+ *     description = "Car assistant with persistent conversations";
+ *     instructions = "You are a helpful car expert...";
+ *     tools = ["search-cars"];
+ *
+ *     protected async loadConversation(conversationId: string) {
+ *         const conv = await this.ctx.repos.conversationRepo.getById(conversationId);
+ *         return conv ? {
+ *             messages: conv.messages,
+ *             providerMetadata: conv.providerMetadata,
+ *         } : null;
+ *     }
+ *
+ *     protected async saveConversation(
+ *         conversationId: string,
+ *         data: ConversationData,
+ *         result: AgentExecuteResult,
+ *         context: AgentFinishContext
+ *     ) {
+ *         await this.ctx.repos.conversationRepo.upsert({
+ *             _id: conversationId,
+ *             agentId: this.id,
+ *             userId: context.user?.id,
+ *             messages: data.messages,
+ *             providerMetadata: data.providerMetadata,
+ *             updatedAt: new Date(),
+ *         });
+ *     }
+ * }
+ * ```
+ *
+ * ### Redis Storage
+ * ```typescript
+ * export default class CarAgent extends ConversationAgent<AppContext> {
+ *     id = "car-agent";
+ *     description = "Car assistant with Redis-backed conversations";
+ *     instructions = "You are a helpful car expert...";
+ *     tools = ["search-cars"];
+ *
+ *     protected async loadConversation(conversationId: string) {
+ *         const key = `conversation:${conversationId}`;
+ *         const data = await this.ctx.redis.get(key);
+ *         return data ? JSON.parse(data) : null;
+ *     }
+ *
+ *     protected async saveConversation(
+ *         conversationId: string,
+ *         data: ConversationData
+ *     ) {
+ *         const key = `conversation:${conversationId}`;
+ *         await this.ctx.redis.setex(
+ *             key,
+ *             86400, // 24 hour TTL
+ *             JSON.stringify(data)
+ *         );
+ *     }
+ * }
+ * ```
+ *
+ * ### In-Memory Storage (Development/Testing)
+ * ```typescript
+ * const conversationStore = new Map<string, ConversationData>();
+ *
+ * export default class CarAgent extends ConversationAgent<AppContext> {
+ *     id = "car-agent";
+ *     description = "Car assistant with in-memory conversations";
+ *     instructions = "You are a helpful car expert...";
+ *     tools = ["search-cars"];
+ *
+ *     protected async loadConversation(conversationId: string) {
+ *         return conversationStore.get(conversationId) || null;
+ *     }
+ *
+ *     protected async saveConversation(
+ *         conversationId: string,
+ *         data: ConversationData
+ *     ) {
+ *         conversationStore.set(conversationId, data);
+ *     }
+ * }
+ * ```
+ *
+ * ## Handler Usage
+ *
+ * ```typescript
+ * const handler: PostHandler<AppContext, Input, Output> = async ({ ctx, body, req }) => {
+ *     const conversationId = body.conversationId || generateId();
+ *
+ *     const result = await ctx.agents.carAgent
+ *         .withUser(req.user)
+ *         .execute({ message: body.message, conversationId });
+ *
+ *     return {
+ *         conversationId,
+ *         message: (await result.result).message,
+ *     };
+ * };
+ * ```
+ *
+ * ## Provider Metadata Flow
+ *
+ * 1. First turn: Agent executes, LLM returns metadata (e.g., `{ openai: { responseId: "..." } }`)
+ * 2. saveConversation() stores messages + metadata
+ * 3. Second turn: loadConversation() returns messages + metadata
+ * 4. beforeRun() populates input.providerMetadata (always preserved)
+ * 5. LLM adapter receives metadata for tracking/debugging purposes
+ * 6. Full conversation history is always sent to ensure reliability
+ *
+ * @template Context - Application context type extending FlinkContext
+ *
+ * @see {@link https://flink.dev/docs/ai/agents/persistence | Persistence Guide}
+ * @see {@link https://platform.openai.com/docs/guides/conversation-history | OpenAI Conversation History}
+ */
+export abstract class ConversationAgent<Context extends FlinkContext = FlinkContext> extends FlinkAgent<Context> {
+    /**
+     * Load conversation history and provider metadata for the given conversation ID.
+     *
+     * Called automatically in beforeRun() before agent execution.
+     *
+     * @param conversationId - Unique identifier for the conversation
+     * @returns Conversation data (messages + providerMetadata), or null if not found
+     *
+     * @example
+     * ```typescript
+     * protected async loadConversation(conversationId: string) {
+     *     const conv = await this.ctx.repos.conversationRepo.getById(conversationId);
+     *     return conv ? {
+     *         messages: conv.messages,
+     *         providerMetadata: conv.providerMetadata,
+     *     } : null;
+     * }
+     * ```
+     */
+    protected abstract loadConversation(conversationId: string): Promise<ConversationData | null>;
+
+    /**
+     * Save conversation history and provider metadata.
+     *
+     * Called automatically in afterRun() after agent execution completes successfully.
+     *
+     * @param conversationId - Unique identifier for the conversation
+     * @param data - Conversation data to save (messages + providerMetadata)
+     * @param result - Agent execution result (for access to final output if needed)
+     * @param context - Agent finish context (includes user, isSubAgent, etc.)
+     *
+     * @example
+     * ```typescript
+     * protected async saveConversation(
+     *     conversationId: string,
+     *     data: ConversationData,
+     *     result: AgentExecuteResult,
+     *     context: AgentFinishContext
+     * ) {
+     *     await this.ctx.repos.conversationRepo.upsert({
+     *         _id: conversationId,
+     *         agentId: this.id,
+     *         userId: context.user?.id,
+     *         messages: data.messages,
+     *         providerMetadata: data.providerMetadata,
+     *         updatedAt: new Date(),
+     *     });
+     * }
+     * ```
+     */
+    protected abstract saveConversation(conversationId: string, data: ConversationData, result: AgentExecuteResult, context: AgentFinishContext): Promise<void>;
+
+    /**
+     * Lifecycle hook: Load conversation history before agent execution.
+     *
+     * Automatically populates input.history and input.providerMetadata from storage.
+     *
+     * @internal
+     */
+    protected async beforeRun(input: AgentExecuteInput, context: AgentExecuteContext): Promise<void> {
+        const conversationId = input.conversationId;
+
+        if (!conversationId) {
+            logger.debug(`[${this.id}] No conversationId provided, starting fresh conversation`);
+            return;
+        }
+
+        try {
+            const conversationData = await this.loadConversation(conversationId);
+
+            if (conversationData) {
+                input.history = this.convertToAgentMessages(conversationData.messages);
+
+                // Always preserve provider metadata (for tracking and future use)
+                input.providerMetadata = conversationData.providerMetadata;
+
+                logger.debug(`[${this.id}] Loaded conversation ${conversationId}: ${conversationData.messages.length} messages`);
+            } else {
+                logger.debug(`[${this.id}] No conversation found for ${conversationId}, starting fresh`);
+            }
+        } catch (error) {
+            logger.error(`[${this.id}] Failed to load conversation ${conversationId}:`, error);
+            throw error; // Propagate load errors
+        }
+    }
+
+    /**
+     * Lifecycle hook: Save conversation history after agent execution.
+     *
+     * Automatically converts LLM messages to storage format and saves with provider metadata.
+     * Skips save for sub-agent calls (parent agent handles persistence).
+     *
+     * @internal
+     */
+    protected async afterRun(result: AgentExecuteResult, context: AgentFinishContext): Promise<void> {
+        const conversationId = context.conversationId;
+
+        if (!conversationId) {
+            logger.debug(`[${this.id}] No conversationId provided, skipping save`);
+            return;
+        }
+
+        try {
+            const messages = this.convertToMessages(context.messages);
+            const providerMetadata = result.providerMetadata;
+
+            const conversationData: ConversationData = {
+                messages,
+                providerMetadata,
+            };
+
+            await this.saveConversation(conversationId, conversationData, result, context);
+
+            logger.debug(`[${this.id}] Saved conversation ${conversationId}: ${messages.length} messages, metadata=${JSON.stringify(providerMetadata)}`);
+        } catch (error) {
+            // Log but don't throw - request already succeeded, don't fail it now
+            logger.error(`[${this.id}] Failed to save conversation ${conversationId}:`, error);
+        }
+    }
+
+    /**
+     * Convert storage messages back to agent Message format for input.history.
+     *
+     * @param storageMessages - Messages from storage in StorageMessage format
+     * @returns Message array compatible with AgentExecuteInput.history
+     *
+     * @internal
+     */
+    private convertToAgentMessages(storageMessages: StorageMessage[]): Message[] {
+        return storageMessages.flatMap((msg): Message[] => {
+            // Check for tool results first (can be on user or tool role messages)
+            if (msg.toolResults && msg.toolResults.length > 0) {
+                // Tool results stored in storage format, convert to agent format
+                // Each tool result becomes a separate Message
+                return msg.toolResults.map(
+                    (toolResult): Message => ({
+                        role: "tool",
+                        toolCallId: toolResult.id,
+                        toolName: "", // Not stored, but required by type
+                        // Tool results are persisted as already-stringified payloads (see formatResultForAI).
+                        // JSON.stringify-ing again would double-encode strings into escaped JSON literals.
+                        result: typeof toolResult.result === "string" ? toolResult.result : JSON.stringify(toolResult.result),
+                    })
+                );
+            } else if (msg.role === "user") {
+                return [{ role: "user", content: msg.content || "" }];
+            } else if (msg.role === "assistant") {
+                return [
+                    {
+                        role: "assistant",
+                        content: msg.content || "",
+                        toolCalls: msg.toolCalls,
+                    },
+                ];
+            } else {
+                // Fallback for unexpected cases
+                return [{ role: "user", content: msg.content || "" }];
+            }
+        });
+    }
+
+    /**
+     * Convert LLM adapter messages to storage format for persistence.
+     *
+     * @param llmMessages - Messages from LLM adapter in their native format
+     * @returns StorageMessage array
+     *
+     * @internal
+     */
+    private convertToMessages(llmMessages: any[]): StorageMessage[] {
+        return llmMessages.map((msg) => {
+            const message: StorageMessage = {
+                role: msg.role,
+            };
+
+            // Handle content blocks
+            if (Array.isArray(msg.content)) {
+                const text = this.extractTextFromBlocks(msg.content);
+                if (text) message.content = text;
+
+                const toolCalls = this.extractToolCalls(msg.content);
+                if (toolCalls.length > 0) message.toolCalls = toolCalls;
+
+                const toolResults = this.extractToolResults(msg.content);
+                if (toolResults.length > 0) message.toolResults = toolResults;
+            } else if (typeof msg.content === "string") {
+                message.content = msg.content;
+            }
+
+            return message;
+        });
+    }
+
+    /**
+     * Extract text content from message content blocks.
+     *
+     * @param blocks - Content blocks from LLM message
+     * @returns Concatenated text content, or undefined if no text blocks
+     *
+     * @internal
+     */
+    private extractTextFromBlocks(blocks: any[]): string | undefined {
+        const textBlocks = blocks.filter((block) => block.type === "text");
+        if (textBlocks.length === 0) return undefined;
+        return textBlocks.map((block) => block.text).join("");
+    }
+
+    /**
+     * Extract tool calls from message content blocks.
+     *
+     * @param blocks - Content blocks from LLM message
+     * @returns Array of tool call objects
+     *
+     * @internal
+     */
+    private extractToolCalls(blocks: any[]): any[] {
+        return blocks
+            .filter((block) => block.type === "tool_use")
+            .map((block) => ({
+                id: block.id,
+                name: block.name,
+                input: block.input,
+            }));
+    }
+
+    /**
+     * Extract tool results from message content blocks.
+     *
+     * @param blocks - Content blocks from LLM message
+     * @returns Array of tool result objects
+     *
+     * @internal
+     */
+    private extractToolResults(blocks: any[]): any[] {
+        return blocks
+            .filter((block) => block.type === "tool_result")
+            .map((block) => ({
+                id: block.tool_use_id,
+                result: block.content,
+            }));
+    }
+}