@falai/agent 0.9.0-alpha-1 → 0.9.0-alpha-2

package/dist/cjs/src/core/Agent.js

@@ -16,17 +16,39 @@ const ToolExecutor_1 = require("./ToolExecutor");
 const ResponsePipeline_1 = require("./ResponsePipeline");
 const constants_1 = require("../constants");
 /**
- * Main Agent class with generic context support
+ * Error thrown when data validation fails
  */
+class DataValidationError extends Error {
+    constructor(errors, message) {
+        super(message || "Data validation failed");
+        this.errors = errors;
+        this.name = "DataValidationError";
+    }
+}
+/**
+ * Error thrown when route configuration is invalid
+ */
+class RouteConfigurationError extends Error {
+    constructor(routeTitle, invalidFields, message) {
+        super(message || `Route configuration error in '${routeTitle}'`);
+        this.routeTitle = routeTitle;
+        this.invalidFields = invalidFields;
+        this.name = "RouteConfigurationError";
+    }
+}
+/**
+ * Main Agent class with generic context and data support
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 class Agent {
     constructor(options) {
         this.options = options;
         this.terms = [];
         this.guidelines = [];
         this.tools = [];
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.routes = [];
         this.knowledgeBase = {};
+        this.collectedData = {};
         // Set log level based on debug option
         if (options.debug) {
             utils_1.logger.setLevel(utils_1.LoggerLevel.DEBUG);
@@ -35,8 +57,25 @@ class Agent {
         if (options.context !== undefined && options.contextProvider) {
             throw new Error("Cannot provide both 'context' and 'contextProvider'. Choose one.");
         }
+        // Initialize and validate agent-level schema if provided
+        if (options.schema) {
+            this.schema = options.schema;
+            this.validateSchema(this.schema);
+            utils_1.logger.debug("[Agent] Agent-level schema initialized and validated");
+        }
         // Initialize context if provided
         this.context = options.context;
+        // Initialize collected data with initial data if provided
+        if (options.initialData) {
+            if (this.schema) {
+                const validation = this.validateData(options.initialData);
+                if (!validation.valid) {
+                    throw new Error(`Initial data validation failed: ${validation.errors.map(e => e.message).join(', ')}`);
+                }
+            }
+            this.collectedData = { ...options.initialData };
+            utils_1.logger.debug("[Agent] Initial data set:", this.collectedData);
+        }
         // Initialize current session if provided
         this.currentSession = options.session;
         // Initialize routing and response engines
@@ -46,15 +85,32 @@ class Agent {
             switchThreshold: 70,
         });
         this.responseEngine = new ResponseEngine_1.ResponseEngine();
-        this.responsePipeline = new ResponsePipeline_1.ResponsePipeline(options, this.routes, this.tools, this.routingEngine, this.updateContext.bind(this), this.updateData.bind(this));
+        this.responsePipeline = new ResponsePipeline_1.ResponsePipeline(options, this.routes, this.tools, this.routingEngine, this.updateContext.bind(this), this.updateData.bind(this), this.updateCollectedData.bind(this));
         // Initialize persistence if configured
         if (options.persistence) {
-            this.persistenceManager = new PersistenceManager_1.PersistenceManager(options.persistence);
-            // Initialize the adapter if it has an initialize method
-            if (options.persistence.adapter.initialize) {
-                options.persistence.adapter.initialize().catch((error) => {
-                    utils_1.logger.error("[Agent] Persistence adapter initialization failed:", error);
-                });
+            try {
+                // Validate persistence configuration
+                if (!options.persistence.adapter) {
+                    throw new Error("Persistence adapter is required when persistence is configured");
+                }
+                if (!options.persistence.adapter.sessionRepository) {
+                    throw new Error("Persistence adapter must provide a sessionRepository");
+                }
+                if (!options.persistence.adapter.messageRepository) {
+                    throw new Error("Persistence adapter must provide a messageRepository");
+                }
+                this.persistenceManager = new PersistenceManager_1.PersistenceManager(options.persistence);
+                // Initialize the adapter if it has an initialize method
+                if (options.persistence.adapter.initialize) {
+                    options.persistence.adapter.initialize().catch((error) => {
+                        utils_1.logger.error("[Agent] Persistence adapter initialization failed:", error instanceof Error ? error.message : String(error));
+                    });
+                }
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                utils_1.logger.error("[Agent] Failed to initialize persistence:", errorMessage);
+                throw new Error(`Failed to initialize persistence: ${errorMessage}`);
             }
         }
         // Initialize from options - use create methods for consistency
@@ -92,6 +148,116 @@ class Agent {
             });
         }
     }
+    /**
+     * Validate the agent-level schema structure
+     * @private
+     */
+    validateSchema(schema) {
+        if (!schema || typeof schema !== 'object') {
+            throw new Error("Agent schema must be a valid JSON Schema object. " +
+                "Provide a schema with 'type': 'object' and 'properties' to define the data structure.");
+        }
+        if (schema.type !== 'object') {
+            throw new Error(`Agent schema must be of type 'object', but received '${String(schema.type)}'. ` +
+                "Agent-level schemas must define object structures for data collection.");
+        }
+        if (!schema.properties || typeof schema.properties !== 'object') {
+            throw new Error("Agent schema must have a 'properties' field defining the data fields. " +
+                "Example: { type: 'object', properties: { name: { type: 'string' }, email: { type: 'string' } } }");
+        }
+        utils_1.logger.debug("[Agent] Schema validation passed");
+    }
+    /**
+     * Validate data against the agent-level schema
+     */
+    validateData(data) {
+        if (!this.schema) {
+            // No schema defined, consider all data valid
+            return { valid: true, errors: [], warnings: [] };
+        }
+        const errors = [];
+        const warnings = [];
+        // Basic validation - check if provided fields exist in schema
+        if (this.schema.properties) {
+            for (const [key, value] of Object.entries(data)) {
+                if (!(key in this.schema.properties)) {
+                    errors.push({
+                        field: key,
+                        value,
+                        message: `Field '${key}' is not defined in agent schema`,
+                        schemaPath: `properties.${key}`
+                    });
+                }
+            }
+        }
+        // Check required fields if specified
+        if (this.schema.required && Array.isArray(this.schema.required)) {
+            for (const requiredField of this.schema.required) {
+                if (!(requiredField in data) || data[requiredField] === undefined) {
+                    warnings.push({
+                        field: requiredField,
+                        value: undefined,
+                        message: `Required field '${requiredField}' is missing`,
+                        schemaPath: `required`
+                    });
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    /**
+     * Check if a field is valid according to the agent schema
+     * @param field - The field key to validate
+     * @returns true if field exists in schema or no schema is defined, false otherwise
+     */
+    isValidSchemaField(field) {
+        if (!this.schema || !this.schema.properties) {
+            // No schema defined, consider all fields valid
+            return true;
+        }
+        return field in this.schema.properties;
+    }
+    /**
+     * Get the current collected data
+     */
+    getCollectedData() {
+        return { ...this.collectedData };
+    }
+    /**
+     * Update collected data with validation
+     */
+    async updateCollectedData(updates) {
+        // Validate the updates
+        const validation = this.validateData(updates);
+        if (!validation.valid) {
+            const errorMessages = validation.errors.map(e => e.message).join(', ');
+            throw new DataValidationError(validation.errors, `Data validation failed: ${errorMessages}`);
+        }
+        // Log warnings if any
+        if (validation.warnings.length > 0) {
+            const warningMessages = validation.warnings.map(w => w.message).join(', ');
+            utils_1.logger.warn(`[Agent] Data validation warnings: ${warningMessages}`);
+        }
+        // Merge updates with current data
+        const previousData = { ...this.collectedData };
+        this.collectedData = {
+            ...this.collectedData,
+            ...updates
+        };
+        // Trigger agent-level lifecycle hook if configured
+        if (this.options.hooks?.onDataUpdate) {
+            this.collectedData = await this.options.hooks.onDataUpdate(this.collectedData, previousData);
+        }
+        // Update current session if it exists to keep it in sync
+        if (this.currentSession) {
+            this.currentSession = (0, utils_1.mergeCollected)(this.currentSession, this.collectedData);
+        }
+        utils_1.logger.debug("[Agent] Collected data updated:", updates);
+    }
     /**
      * Get agent name
      */
@@ -117,10 +283,25 @@ class Agent {
         return this.options.identity;
     }
     /**
-     * Create a new route (journey)
-     * @template TData - Type of data collected throughout the route
+     * Create a new route (journey) using agent-level data type
      */
     createRoute(options) {
+        // Validate that requiredFields exist in agent schema
+        if (options.requiredFields && this.schema?.properties) {
+            const invalidRequiredFields = options.requiredFields.filter(field => !(String(field) in this.schema.properties));
+            if (invalidRequiredFields.length > 0) {
+                throw new RouteConfigurationError(options.title, invalidRequiredFields.map(f => String(f)), `Invalid required fields in route '${options.title}': ${invalidRequiredFields.join(', ')}. ` +
+                    `Must be valid keys from agent schema. Available fields: ${Object.keys(this.schema.properties).join(', ')}.`);
+            }
+        }
+        // Validate that optionalFields exist in agent schema
+        if (options.optionalFields && this.schema?.properties) {
+            const invalidOptionalFields = options.optionalFields.filter(field => !(String(field) in this.schema.properties));
+            if (invalidOptionalFields.length > 0) {
+                throw new RouteConfigurationError(options.title, invalidOptionalFields.map(f => String(f)), `Invalid optional fields in route '${options.title}': ${invalidOptionalFields.join(', ')}. ` +
+                    `Must be valid keys from agent schema. Available fields: ${Object.keys(this.schema.properties).join(', ')}.`);
+            }
+        }
         const route = new Route_1.Route(options);
         this.routes.push(route);
         return route;
@@ -205,6 +386,8 @@ class Agent {
         if (this.options.hooks?.onDataUpdate) {
             newCollected = (await this.options.hooks.onDataUpdate(newCollected, previousCollected));
         }
+        // Update agent's collected data to stay in sync
+        this.collectedData = { ...newCollected };
         // Return updated session
         return (0, utils_1.mergeCollected)(session, newCollected);
     }
@@ -219,6 +402,12 @@ class Agent {
         // Otherwise return the stored context
         return this.context;
     }
+    /**
+     * Get current schema
+     */
+    getSchema() {
+        return this.schema;
+    }
     /**
      * Generate a response based on history and context as a stream
      */
@@ -235,6 +424,11 @@ class Agent {
         });
         const { effectiveContext } = responseContext;
         session = responseContext.session;
+        // Merge agent's collected data into session (agent data takes precedence)
+        if (Object.keys(this.collectedData).length > 0) {
+            session = (0, utils_1.mergeCollected)(session, this.collectedData);
+            utils_1.logger.debug("[Agent] Merged agent collected data into session:", this.collectedData);
+        }
         // Update our stored context if it was modified by beforeRespond hook
         this.context = this.responsePipeline.getStoredContext();
         // PHASE 1: PREPARE - Execute prepare function if current step has one
@@ -274,7 +468,7 @@ class Agent {
             // Get last user message
             const lastUserMessage = (0, utils_1.getLastMessageFromHistory)(history);
             // Build response schema for this route (with collect fields from step)
-            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, nextStep);
+            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, nextStep, this.schema);
             // Check if selected route and next step are defined
             if (!selectedRoute || !nextStep) {
                 utils_1.logger.error("[Agent] Selected route or next step is not defined", {
@@ -301,6 +495,7 @@ class Agent {
                 combinedTerms: this.mergeTerms(this.getTerms(), selectedRoute.getTerms()),
                 context: effectiveContext,
                 session,
+                agentSchema: this.schema,
             });
             // Collect available tools for AI
             const availableTools = this.collectAvailableTools(selectedRoute, nextStep);
@@ -336,6 +531,7 @@ class Agent {
                                 tool: tool,
                                 context: effectiveContext,
                                 updateContext: this.updateContext.bind(this),
+                                updateData: this.updateCollectedData.bind(this),
                                 history,
                                 data: session.data,
                                 toolArguments: toolCall.arguments,
@@ -419,6 +615,7 @@ class Agent {
                                 tool: tool,
                                 context: effectiveContext,
                                 updateContext: this.updateContext.bind(this),
+                                updateData: this.updateCollectedData.bind(this),
                                 history: updatedHistory,
                                 data: session.data,
                                 toolArguments: toolCall.arguments,
@@ -452,12 +649,16 @@ class Agent {
                     // The structured response includes both base fields and collected extraction fields
                     const structuredData = chunk.structured;
                     for (const field of nextStep.collect) {
-                        if (field in structuredData) {
-                            collectedData[field] = structuredData[field];
+                        const fieldKey = String(field);
+                        if (fieldKey in structuredData) {
+                            collectedData[fieldKey] = structuredData[fieldKey];
                         }
                     }
-                    // Merge collected data into session
+                    // Merge collected data into session using agent-level data validation
                     if (Object.keys(collectedData).length > 0) {
+                        // Update agent-level collected data with validation
+                        await this.updateCollectedData(collectedData);
+                        // Update session with validated data
                         session = await this.updateData(session, collectedData);
                         utils_1.logger.debug(`[Agent] Collected data:`, collectedData);
                     }
@@ -520,7 +721,7 @@ class Agent {
                     "Summarize what was accomplished and confirm completion based on the conversation history and collected data",
             });
             // Build response schema for completion
-            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, completionStep);
+            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, completionStep, this.schema);
             const templateContext = {
                 context: effectiveContext,
                 session,
@@ -544,6 +745,7 @@ class Agent {
                 combinedTerms: this.mergeTerms(this.getTerms(), selectedRoute.getTerms()),
                 context: effectiveContext,
                 session,
+                agentSchema: this.schema,
             });
             // Stream completion message using AI provider
             const stream = this.options.provider.generateMessageStream({
@@ -669,6 +871,11 @@ class Agent {
         let session = (0, utils_1.cloneDeep)(params.session) ||
             (0, utils_1.cloneDeep)(this.currentSession) ||
             (await this.session.getOrCreate());
+        // Merge agent's collected data into session (agent data takes precedence)
+        if (Object.keys(this.collectedData).length > 0) {
+            session = (0, utils_1.mergeCollected)(session, this.collectedData);
+            utils_1.logger.debug("[Agent] Merged agent collected data into session:", this.collectedData);
+        }
         // PHASE 1: PREPARE - Execute prepare function if current step has one
         if (session.currentRoute && session.currentStep) {
             const currentRoute = this.routes.find((r) => r.id === session.currentRoute?.id);
@@ -766,7 +973,7 @@ class Agent {
             // Get last user message
             const lastUserMessage = (0, utils_1.getLastMessageFromHistory)(history);
             // Build response schema for this route (with collect fields from step)
-            responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, nextStep);
+            responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, nextStep, this.schema);
             // Build response prompt
             responsePrompt = await this.responseEngine.buildResponsePrompt({
                 route: selectedRoute,
@@ -785,6 +992,7 @@ class Agent {
                 combinedTerms: this.mergeTerms(this.getTerms(), selectedRoute.getTerms()),
                 context: effectiveContext,
                 session,
+                agentSchema: this.schema,
             });
             // Collect available tools for AI
             availableTools = this.collectAvailableTools(selectedRoute, nextStep);
@@ -802,7 +1010,7 @@ class Agent {
                 session,
             });
             // Use agent-level tools only
-            availableTools = [...this.tools];
+            availableTools = this.collectAvailableTools();
             responseSchema = undefined;
         }
         // Generate message using AI provider (common for both route and no-route cases)
@@ -837,6 +1045,7 @@ class Agent {
                         tool: tool,
                         context: effectiveContext,
                         updateContext: this.updateContext.bind(this),
+                        updateData: this.updateCollectedData.bind(this),
                         history,
                         data: session.data,
                         toolArguments: toolCall.arguments,
@@ -915,6 +1124,7 @@ class Agent {
                         tool: tool,
                         context: effectiveContext,
                         updateContext: this.updateContext.bind(this),
+                        updateData: this.updateCollectedData.bind(this),
                         history: updatedHistory,
                         data: session.data,
                         toolArguments: toolCall.arguments,
@@ -949,12 +1159,16 @@ class Agent {
             // The structured response includes both base fields and collected extraction fields
             const structuredData = result.structured;
             for (const field of nextStep.collect) {
-                if (field in structuredData) {
-                    collectedData[field] = structuredData[field];
+                const fieldKey = String(field);
+                if (fieldKey in structuredData) {
+                    collectedData[fieldKey] = structuredData[fieldKey];
                 }
             }
-            // Merge collected data into session
+            // Merge collected data into session using agent-level data validation
             if (Object.keys(collectedData).length > 0) {
+                // Update agent-level collected data with validation
+                await this.updateCollectedData(collectedData);
+                // Update session with validated data
                 session = await this.updateData(session, collectedData);
                 utils_1.logger.debug(`[Agent] Collected data:`, collectedData);
             }
@@ -980,16 +1194,16 @@ class Agent {
                 prompt: endStepSpec.prompt ||
                     "Summarize what was accomplished and confirm completion based on the conversation history and collected data",
             });
+            if (!selectedRoute) {
+                throw new Error("Selected route is not defined");
+            }
             // Build response schema for completion
-            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, completionStep);
+            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, completionStep, this.schema);
             const templateContext = {
                 context: effectiveContext,
                 session,
                 history,
             };
-            if (!selectedRoute) {
-                throw new Error("Selected route is not defined");
-            }
             // Build completion response prompt
             const completionPrompt = await this.responseEngine.buildResponsePrompt({
                 route: selectedRoute,
@@ -1008,6 +1222,7 @@ class Agent {
                 combinedTerms: this.mergeTerms(this.getTerms(), selectedRoute.getTerms()),
                 context: effectiveContext,
                 session,
+                agentSchema: this.schema,
             });
             // Generate completion message using AI provider
             const completionResult = await this.options.provider.generateMessage({
@@ -1253,6 +1468,7 @@ class Agent {
                     tool,
                     context,
                     updateContext: this.updateContext.bind(this),
+                    updateData: this.updateCollectedData.bind(this),
                     history: [], // Empty history for prepare/finalize
                     data,
                 });
@@ -1330,19 +1546,19 @@ class Agent {
         this.currentSession = undefined;
     }
     /**
-     * Get collected data from current session
+     * Get collected data from current session or agent-level collected data
      * @param routeId - Optional route ID to get data for (uses current route if not provided)
-     * @returns The collected data from the current session
+     * @returns The collected data from the current session or agent-level data
      */
-    getData(routeId) {
-        if (!this.currentSession) {
-            return {};
-        }
-        if (routeId) {
-            return (this.currentSession.dataByRoute?.[routeId] ||
-                {});
+    getData() {
+        // If we have a current session, use session data
+        if (this.currentSession) {
+            // With agent-level data, all routes share the same data structure
+            // No need for route-specific data access
+            return (this.currentSession.data) || {};
         }
-        return this.currentSession.data || {};
+        // Otherwise, return agent-level collected data
+        return this.getCollectedData();
     }
     /**
      * Manually transition to a different route
@@ -1385,14 +1601,14 @@ class Agent {
             pendingTransition: {
                 targetRouteId: targetRoute.id,
                 condition: renderedCondition,
-                reason: "manual",
+                reason: "route_complete",
             },
         };
         // Update current session if using it
         if (!session && this.currentSession) {
             this.currentSession = updatedSession;
         }
-        utils_1.logger.debug(`[Agent] Set pending manual transition to route: ${targetRoute.title}`);
+        utils_1.logger.debug(`[Agent] Set pending transition to route: ${targetRoute.title}`);
         return updatedSession;
     }
     /**
@@ -1414,7 +1630,14 @@ class Agent {
             history = this.session.getHistory();
         }
         // Get or create session
-        const session = await this.session.getOrCreate();
+        let session = await this.session.getOrCreate();
+        // Merge agent's collected data into session (agent data takes precedence)
+        if (Object.keys(this.collectedData).length > 0) {
+            session = (0, utils_1.mergeCollected)(session, this.collectedData);
+            // Update the session manager with the merged data
+            await this.session.setData(this.collectedData);
+            utils_1.logger.debug("[Agent] Merged agent collected data into chat session:", this.collectedData);
+        }
         // Use existing respond method with session-managed history
         const result = await this.respond({
             history,
@@ -1426,7 +1649,11 @@ class Agent {
         if (!options?.history) {
             await this.session.addMessage("assistant", result.message);
         }
-        return result;
+        // Ensure the result includes the current session
+        return {
+            ...result,
+            session: result.session || this.session.current,
+        };
     }
 }
 exports.Agent = Agent;