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

package/spec/mock-project/dist/src/ai/ConversationFlinkAgent.js

@@ -0,0 +1,422 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+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 };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConversationAgent = void 0;
+var FlinkAgent_1 = require("./FlinkAgent");
+var FlinkLog_1 = require("../FlinkLog");
+/**
+ * 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
+ *
+ * - **Cost Savings**: Automatic provider metadata persistence enables server-side optimizations
+ * - **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)
+ *
+ * ## 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: "...", instructionsHash: "..." } }`)
+ * 2. saveConversation() stores messages + metadata
+ * 3. Second turn: loadConversation() returns messages + metadata
+ * 4. beforeRun() populates input.providerMetadata
+ * 5. LLM adapter uses metadata for server-side optimization (e.g., OpenAI's previousResponseId)
+ * 6. Result: 40-80% cost savings on subsequent turns
+ *
+ * @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}
+ */
+var ConversationAgent = /** @class */ (function (_super) {
+    __extends(ConversationAgent, _super);
+    function ConversationAgent() {
+        var _this = _super !== null && _super.apply(this, arguments) || this;
+        /**
+         * Default persistence strategy for this agent.
+         * Can be overridden per-execution via execute() options.
+         *
+         * @default "auto"
+         */
+        _this.persistenceStrategy = "auto";
+        return _this;
+    }
+    /**
+     * Lifecycle hook: Load conversation history before agent execution.
+     *
+     * Automatically populates input.history and input.providerMetadata from storage.
+     *
+     * @internal
+     */
+    ConversationAgent.prototype.beforeRun = function (input, context) {
+        return __awaiter(this, void 0, void 0, function () {
+            var conversationId, conversationData, strategy, error_1;
+            var _a, _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0:
+                        conversationId = input.conversationId;
+                        if (!conversationId) {
+                            FlinkLog_1.log.debug("[".concat(this.id, "] No conversationId provided, starting fresh conversation"));
+                            return [2 /*return*/];
+                        }
+                        _c.label = 1;
+                    case 1:
+                        _c.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, this.loadConversation(conversationId)];
+                    case 2:
+                        conversationData = _c.sent();
+                        if (conversationData) {
+                            input.history = this.convertToAgentMessages(conversationData.messages);
+                            strategy = (_b = (_a = input.options) === null || _a === void 0 ? void 0 : _a.persistenceStrategy) !== null && _b !== void 0 ? _b : this.persistenceStrategy;
+                            if (strategy === "full-history") {
+                                // Clear provider metadata to force full history
+                                input.providerMetadata = undefined;
+                                FlinkLog_1.log.debug("[".concat(this.id, "] Strategy: full-history - clearing provider metadata"));
+                            }
+                            else {
+                                // "auto" or "provider-optimized" - preserve metadata
+                                input.providerMetadata = conversationData.providerMetadata;
+                                FlinkLog_1.log.debug("[".concat(this.id, "] Strategy: ").concat(strategy, " - using provider metadata"), { metadata: conversationData.providerMetadata });
+                            }
+                            FlinkLog_1.log.debug("[".concat(this.id, "] Loaded conversation ").concat(conversationId, ": ").concat(conversationData.messages.length, " messages"));
+                        }
+                        else {
+                            FlinkLog_1.log.debug("[".concat(this.id, "] No conversation found for ").concat(conversationId, ", starting fresh"));
+                        }
+                        return [3 /*break*/, 4];
+                    case 3:
+                        error_1 = _c.sent();
+                        FlinkLog_1.log.error("[".concat(this.id, "] Failed to load conversation ").concat(conversationId, ":"), error_1);
+                        throw error_1; // Propagate load errors
+                    case 4: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * 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
+     */
+    ConversationAgent.prototype.afterRun = function (result, context) {
+        return __awaiter(this, void 0, void 0, function () {
+            var conversationId, messages, providerMetadata, conversationData, error_2;
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        conversationId = (_a = context.input) === null || _a === void 0 ? void 0 : _a.conversationId;
+                        if (!conversationId) {
+                            FlinkLog_1.log.debug("[".concat(this.id, "] No conversationId provided, skipping save"));
+                            return [2 /*return*/];
+                        }
+                        // Skip save for sub-agent calls - parent handles persistence
+                        if (context.isSubAgent) {
+                            FlinkLog_1.log.debug("[".concat(this.id, "] Sub-agent execution, skipping save (parent handles persistence)"));
+                            return [2 /*return*/];
+                        }
+                        _b.label = 1;
+                    case 1:
+                        _b.trys.push([1, 3, , 4]);
+                        messages = this.convertToMessages(context.messages);
+                        providerMetadata = result.providerMetadata;
+                        conversationData = {
+                            messages: messages,
+                            providerMetadata: providerMetadata,
+                        };
+                        return [4 /*yield*/, this.saveConversation(conversationId, conversationData, result, context)];
+                    case 2:
+                        _b.sent();
+                        FlinkLog_1.log.debug("[".concat(this.id, "] Saved conversation ").concat(conversationId, ": ").concat(messages.length, " messages, metadata=").concat(JSON.stringify(providerMetadata)));
+                        return [3 /*break*/, 4];
+                    case 3:
+                        error_2 = _b.sent();
+                        // Log but don't throw - request already succeeded, don't fail it now
+                        FlinkLog_1.log.error("[".concat(this.id, "] Failed to save conversation ").concat(conversationId, ":"), error_2);
+                        return [3 /*break*/, 4];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * 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
+     */
+    ConversationAgent.prototype.convertToAgentMessages = function (storageMessages) {
+        return storageMessages.map(function (msg) {
+            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 if (msg.role === "tool" && msg.toolResults && msg.toolResults.length > 0) {
+                // Tool results stored in storage format, convert to agent format
+                var toolResult = msg.toolResults[0]; // Take first result
+                return {
+                    role: "tool",
+                    toolCallId: toolResult.id,
+                    toolName: "", // Not stored, but required by type
+                    result: JSON.stringify(toolResult.result),
+                };
+            }
+            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
+     */
+    ConversationAgent.prototype.convertToMessages = function (llmMessages) {
+        var _this = this;
+        return llmMessages.map(function (msg) {
+            var message = {
+                role: msg.role,
+            };
+            // Handle content blocks
+            if (Array.isArray(msg.content)) {
+                var text = _this.extractTextFromBlocks(msg.content);
+                if (text)
+                    message.content = text;
+                var toolCalls = _this.extractToolCalls(msg.content);
+                if (toolCalls.length > 0)
+                    message.toolCalls = toolCalls;
+                var 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
+     */
+    ConversationAgent.prototype.extractTextFromBlocks = function (blocks) {
+        var textBlocks = blocks.filter(function (block) { return block.type === "text"; });
+        if (textBlocks.length === 0)
+            return undefined;
+        return textBlocks.map(function (block) { return block.text; }).join("");
+    };
+    /**
+     * Extract tool calls from message content blocks.
+     *
+     * @param blocks - Content blocks from LLM message
+     * @returns Array of tool call objects
+     *
+     * @internal
+     */
+    ConversationAgent.prototype.extractToolCalls = function (blocks) {
+        return blocks
+            .filter(function (block) { return block.type === "tool_use"; })
+            .map(function (block) { return ({
+            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
+     */
+    ConversationAgent.prototype.extractToolResults = function (blocks) {
+        return blocks
+            .filter(function (block) { return block.type === "tool_result"; })
+            .map(function (block) { return ({
+            id: block.tool_use_id,
+            result: block.content,
+        }); });
+    };
+    return ConversationAgent;
+}(FlinkAgent_1.FlinkAgent));
+exports.ConversationAgent = ConversationAgent;