@falai/agent 0.1.0-alpha2

package/dist/src/core/Agent.js

@@ -0,0 +1,737 @@
+/**
+ * Core Agent implementation
+ */
+import { mergeCollected, logger, LoggerLevel, render, createTemplateContext, createConditionEvaluator, } from "../utils";
+import { Route } from "./Route";
+import { PersistenceManager } from "./PersistenceManager";
+import { SessionManager } from "./SessionManager";
+import { RoutingEngine } from "./RoutingEngine";
+import { ResponseModal } from "./ResponseModal";
+import { ToolManager } from "./ToolManager";
+/**
+ * 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
+export class Agent {
+    constructor(options) {
+        this.options = options;
+        this.terms = [];
+        this.guidelines = [];
+        this.tools = [];
+        this.routes = [];
+        this.knowledgeBase = {};
+        this.collectedData = {};
+        // Set log level based on debug option
+        if (options.debug) {
+            logger.setLevel(LoggerLevel.DEBUG);
+        }
+        // Validate context configuration
+        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);
+            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 };
+            logger.debug("[Agent] Initial data set:", this.collectedData);
+        }
+        // Initialize current session if provided
+        this.currentSession = options.session;
+        // Initialize routing engine
+        this.routingEngine = new RoutingEngine({
+            maxCandidates: 5,
+            allowRouteSwitch: true,
+            switchThreshold: 70,
+        });
+        // Initialize ResponseModal for handling all response generation
+        this.responseModal = new ResponseModal(this);
+        // Initialize persistence if configured
+        if (options.persistence) {
+            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(options.persistence);
+                // Initialize the adapter if it has an initialize method
+                if (options.persistence.adapter.initialize) {
+                    options.persistence.adapter.initialize().catch((error) => {
+                        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);
+                logger.error("[Agent] Failed to initialize persistence:", errorMessage);
+                throw new Error(`Failed to initialize persistence: ${errorMessage}`);
+            }
+        }
+        // Initialize from options - use create methods for consistency
+        if (options.terms) {
+            options.terms.forEach((term) => {
+                this.createTerm(term);
+            });
+        }
+        if (options.guidelines) {
+            options.guidelines.forEach((guideline) => {
+                this.createGuideline(guideline);
+            });
+        }
+        if (options.tools) {
+            options.tools.forEach((tool) => {
+                this.createTool(tool);
+            });
+        }
+        if (options.routes) {
+            options.routes.forEach((routeOptions) => {
+                this.createRoute(routeOptions);
+            });
+        }
+        // Initialize knowledge base
+        if (options.knowledgeBase) {
+            this.knowledgeBase = { ...options.knowledgeBase };
+        }
+        // Initialize session manager with reference to this agent for bidirectional sync
+        this.session = new SessionManager(this.persistenceManager, this);
+        // Initialize tool manager with proper type inference
+        this.tool = new ToolManager(this);
+        // Store sessionId for later use in getOrCreate calls
+        if (options.sessionId) {
+            this.session.setDefaultSessionId(options.sessionId);
+            // The session will be loaded on first getOrCreate call
+            this.session.getOrCreate(options.sessionId).then((session) => {
+                // Sync session data to agent collected data
+                if (session.data && Object.keys(session.data).length > 0) {
+                    this.collectedData = { ...session.data };
+                    logger.debug("[Agent] Synced session data to collected data:", this.collectedData);
+                }
+            }).catch((err) => {
+                logger.error("Failed to start session", err);
+            });
+        }
+    }
+    /**
+     * 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' } } }");
+        }
+        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() {
+        // Ensure agent collected data is synced with session
+        this.syncSessionDataToCollectedData();
+        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(', ');
+            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 = mergeCollected(this.currentSession, this.collectedData);
+        }
+        // Also update the session manager's session data (avoid circular call)
+        const sessionManagerSession = this.session.current;
+        if (sessionManagerSession) {
+            sessionManagerSession.data = { ...this.collectedData };
+            sessionManagerSession.metadata.lastUpdatedAt = new Date();
+        }
+        logger.debug("[Agent] Collected data updated:", updates);
+    }
+    /**
+     * Get agent name
+     */
+    get name() {
+        return this.options.name;
+    }
+    /**
+     * Get agent description
+     */
+    get description() {
+        return this.options.description;
+    }
+    /**
+     * Get agent goal
+     */
+    get goal() {
+        return this.options.goal;
+    }
+    /**
+     * Get agent identity
+     */
+    get identity() {
+        return this.options.identity;
+    }
+    /**
+     * 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(options, this);
+        this.routes.push(route);
+        return route;
+    }
+    /**
+     * Create a domain term for the glossary
+     */
+    createTerm(term) {
+        this.terms.push(term);
+        return this;
+    }
+    /**
+     * Create a behavioral guideline
+     */
+    createGuideline(guideline) {
+        const guidelineWithId = {
+            ...guideline,
+            id: guideline.id || `guideline_${this.guidelines.length}`,
+            enabled: guideline.enabled !== false, // Default to true
+        };
+        this.guidelines.push(guidelineWithId);
+        return this;
+    }
+    /**
+     * Add a tool to the agent using the unified Tool interface
+     * Creates and adds the tool to agent scope in one operation (BREAKING CHANGE: replaces createTool)
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    addTool(tool) {
+        // Validate tool before adding
+        if (!tool || !tool.id || !tool.handler) {
+            throw new Error('Invalid tool: must have id and handler properties');
+        }
+        // Add directly to agent's tools array, preserving the TResult type
+        this.tools.push(tool);
+        logger.debug(`[Agent] Added tool to agent scope: ${tool.id}`);
+        return this;
+    }
+    /**
+     * Register a tool at the agent level (legacy method for backward compatibility)
+     * @deprecated Use addTool() with Tool interface instead
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    createTool(tool) {
+        // Validate tool before adding
+        if (!tool || !tool.id || !tool.handler) {
+            throw new Error('Invalid tool: must have id and handler properties');
+        }
+        this.tools.push(tool);
+        logger.debug(`[Agent] Created tool (legacy): ${tool.id}`);
+        return this;
+    }
+    /**
+     * Register multiple tools at the agent level
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    registerTools(tools) {
+        tools.forEach((tool) => {
+            // Validate each tool before adding
+            if (!tool || !tool.id || !tool.handler) {
+                throw new Error(`Invalid tool in batch: must have id and handler properties (tool: ${tool?.id || 'unknown'})`);
+            }
+            this.tools.push(tool);
+        });
+        logger.debug(`[Agent] Registered ${tools.length} tools`);
+        return this;
+    }
+    /**
+     * Update the agent's context
+     * Triggers both agent-level and route-specific onContextUpdate lifecycle hooks if configured
+     */
+    async updateContext(updates) {
+        const previousContext = this.context;
+        // Merge updates with current context
+        this.context = {
+            ...this.context,
+            ...updates,
+        };
+        // Trigger route-specific lifecycle hook if configured and session has current route
+        if (this.currentSession?.currentRoute) {
+            const currentRoute = this.routes.find((r) => r.id === this.currentSession.currentRoute?.id);
+            if (currentRoute?.hooks?.onContextUpdate &&
+                previousContext !== undefined) {
+                await currentRoute.handleContextUpdate(this.context, previousContext);
+            }
+        }
+        // Trigger agent-level lifecycle hook if configured
+        if (this.options.hooks?.onContextUpdate && previousContext !== undefined) {
+            await this.options.hooks.onContextUpdate(this.context, previousContext);
+        }
+    }
+    /**
+     * Update collected data in session with lifecycle hook support
+     * Triggers both agent-level and route-specific onDataUpdate lifecycle hooks if configured
+     * @internal
+     */
+    async updateData(session, dataUpdate) {
+        const previousCollected = { ...session.data };
+        // Merge new collected data
+        let newCollected = {
+            ...session.data,
+            ...dataUpdate,
+        };
+        // Trigger route-specific lifecycle hook if configured and session has a current route
+        if (session.currentRoute) {
+            const currentRoute = this.routes.find((r) => r.id === session.currentRoute?.id);
+            if (currentRoute?.hooks?.onDataUpdate) {
+                newCollected = await currentRoute.handleDataUpdate(newCollected, previousCollected);
+            }
+        }
+        // Trigger agent-level lifecycle hook if configured
+        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 mergeCollected(session, newCollected);
+    }
+    /**
+     * Get current context (fetches from provider if configured)
+     */
+    async getContext() {
+        // If context provider is configured, use it to fetch fresh context
+        if (this.options.contextProvider) {
+            return await this.options.contextProvider();
+        }
+        // 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
+     */
+    async *respondStream(params) {
+        // Delegate to ResponseModal
+        yield* this.responseModal.respondStream(params);
+    }
+    /**
+     * Generate a response based on history and context
+     */
+    async respond(params) {
+        // Delegate to ResponseModal
+        return this.responseModal.respond(params);
+    }
+    /**
+     * Get all routes
+     */
+    getRoutes() {
+        return [...this.routes];
+    }
+    /**
+     * Get agent options
+     * @internal Used by ResponseModal
+     */
+    getAgentOptions() {
+        return this.options;
+    }
+    /**
+     * Get routing engine
+     * @internal Used by ResponseModal
+     */
+    getRoutingEngine() {
+        return this.routingEngine;
+    }
+    /**
+     * Get the updateData method bound to this agent
+     * @internal Used by ResponseModal
+     */
+    getUpdateDataMethod() {
+        return this.updateData.bind(this);
+    }
+    /**
+     * Get all terms
+     */
+    getTerms() {
+        return [...this.terms];
+    }
+    /**
+     * Get all tools
+     */
+    getTools() {
+        return [...this.tools];
+    }
+    /**
+     * Get all guidelines
+     */
+    getGuidelines() {
+        return [...this.guidelines];
+    }
+    /**
+     * Evaluate and match active guidelines based on their conditions
+     * Returns guidelines that should be active given the current context
+     */
+    async evaluateGuidelines(context, session, history) {
+        const templateContext = { context, session, history, data: session?.data };
+        const evaluator = createConditionEvaluator(templateContext);
+        const matches = [];
+        for (const guideline of this.guidelines) {
+            // Skip disabled guidelines
+            if (guideline.enabled === false) {
+                continue;
+            }
+            if (guideline.condition) {
+                const evaluation = await evaluator.evaluateCondition(guideline.condition, 'AND');
+                // Include guideline if:
+                // 1. No programmatic conditions (only strings) - always active
+                // 2. Programmatic conditions evaluate to true
+                if (!evaluation.hasProgrammaticConditions || evaluation.programmaticResult) {
+                    const rationale = evaluation.aiContextStrings.length > 0
+                        ? `Condition met: ${evaluation.aiContextStrings.join(" AND ")}`
+                        : evaluation.hasProgrammaticConditions
+                            ? "Programmatic condition evaluated to true"
+                            : "Always active (no conditions)";
+                    matches.push({
+                        guideline,
+                        rationale
+                    });
+                }
+            }
+            else {
+                // No condition means always active
+                matches.push({
+                    guideline,
+                    rationale: "Always active (no conditions)"
+                });
+            }
+        }
+        return matches;
+    }
+    /**
+     * Get the agent's knowledge base
+     */
+    getKnowledgeBase() {
+        return { ...this.knowledgeBase };
+    }
+    /**
+     * Get the persistence manager (if configured)
+     */
+    getPersistenceManager() {
+        return this.persistenceManager;
+    }
+    /**
+     * Check if persistence is enabled
+     */
+    hasPersistence() {
+        return this.persistenceManager !== undefined;
+    }
+    /**
+     * Set the current session for convenience methods
+     * @param session - Session step to use for subsequent calls
+     */
+    setCurrentSession(session) {
+        this.currentSession = session;
+    }
+    /**
+     * Get the current session (if set)
+     */
+    getCurrentSession() {
+        return this.currentSession;
+    }
+    /**
+     * Execute a prepare or finalize function/tool
+     * @internal Used by ResponseModal
+     */
+    async executePrepareFinalize(prepareOrFinalize, context, data, route, step) {
+        if (!prepareOrFinalize)
+            return;
+        if (typeof prepareOrFinalize === "function") {
+            // It's a function - call it directly
+            await prepareOrFinalize(context, data);
+        }
+        else {
+            // It's a tool reference - find and execute the tool
+            let tool;
+            if (typeof prepareOrFinalize === "string") {
+                // Tool ID - use ToolManager to find it across all scopes
+                tool = this.tool.find(prepareOrFinalize, undefined, step, route);
+            }
+            else {
+                // Tool object - validate it has required properties
+                if (prepareOrFinalize.id && typeof prepareOrFinalize.handler === 'function') {
+                    tool = prepareOrFinalize;
+                }
+                else {
+                    logger.error(`[Agent] Invalid tool object for prepare/finalize: missing id or invalid handler`);
+                    return;
+                }
+            }
+            if (tool) {
+                // Use ToolManager for execution
+                const result = await this.tool.executeTool({
+                    tool,
+                    context,
+                    updateContext: this.updateContext.bind(this),
+                    updateData: this.updateCollectedData.bind(this),
+                    history: [], // Empty history for prepare/finalize
+                    data,
+                });
+                if (!result.success) {
+                    logger.error(`[Agent] Tool execution failed in prepare/finalize: ${result.error}`);
+                    throw new Error(`Tool execution failed: ${result.error}`);
+                }
+            }
+            else {
+                logger.warn(`[Agent] Tool not found for prepare/finalize: ${typeof prepareOrFinalize === "string"
+                    ? prepareOrFinalize
+                    : "inline tool"}`);
+            }
+        }
+    }
+    /**
+     * Clear the current session
+     */
+    clearCurrentSession() {
+        this.currentSession = undefined;
+    }
+    /**
+     * Sync session data to agent collected data
+     * @internal Used to keep agent and session data in sync
+     */
+    syncSessionDataToCollectedData() {
+        const sessionData = this.session.getData();
+        if (sessionData && Object.keys(sessionData).length > 0) {
+            this.collectedData = { ...sessionData };
+            logger.debug("[Agent] Synced session data to collected data:", this.collectedData);
+        }
+    }
+    /**
+     * 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 or agent-level data
+     */
+    getData() {
+        // Ensure agent collected data is synced with session
+        this.syncSessionDataToCollectedData();
+        // 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) || {};
+        }
+        // Otherwise, return agent-level collected data
+        return this.getCollectedData();
+    }
+    /**
+     * Manually transition to a different route
+     * Sets a pending transition that will be executed on the next respond() call
+     *
+     * @param routeIdOrTitle - Route ID or title to transition to
+     * @param session - Session step to update (uses current session if not provided)
+     * @param condition - Optional AI-evaluated condition for the transition
+     * @returns Updated session with pending transition
+     *
+     * @example
+     * // After route completes
+     * if (response.isRouteComplete && response.session) {
+     *   const updatedSession = agent.nextStepRoute("feedback-collection", response.session);
+     *   // Next respond() call will automatically transition to feedback route
+     *   const nextResponse = await agent.respond({ history, session: updatedSession });
+     * }
+     */
+    async nextStepRoute(routeIdOrTitle, session, condition, history) {
+        const targetSession = session || this.currentSession;
+        if (!targetSession) {
+            throw new Error("No session provided and no current session available. Please provide a session to transition.");
+        }
+        // Find target route by ID or title
+        const targetRoute = this.routes.find((r) => r.id === routeIdOrTitle || r.title === routeIdOrTitle);
+        if (!targetRoute) {
+            throw new Error(`Route not found: ${routeIdOrTitle}. Available routes: ${this.routes
+                .map((r) => r.title)
+                .join(", ")}`);
+        }
+        const templateContext = createTemplateContext({
+            context: this.context,
+            session,
+            history,
+            data: this.currentSession?.data,
+        });
+        const renderedCondition = await render(condition, templateContext);
+        const updatedSession = {
+            ...targetSession,
+            pendingTransition: {
+                targetRouteId: targetRoute.id,
+                condition: renderedCondition,
+                reason: "route_complete",
+            },
+        };
+        // Update current session if using it
+        if (!session && this.currentSession) {
+            this.currentSession = updatedSession;
+        }
+        logger.debug(`[Agent] Set pending transition to route: ${targetRoute.title}`);
+        return updatedSession;
+    }
+    /**
+     * Simplified respond method using SessionManager
+     * Automatically manages conversation history through the session
+     */
+    async chat(message, options) {
+        // Delegate to ResponseModal.generate()
+        return this.responseModal.generate(message, options);
+    }
+    /**
+     * Modern streaming API - simple interface like chat() but returns a stream
+     * Automatically manages conversation history through the session
+     */
+    async *stream(message, options) {
+        // Delegate to ResponseModal with the same options structure as chat()
+        yield* this.responseModal.stream(message, {
+            history: options?.history,
+            contextOverride: options?.contextOverride,
+            signal: options?.signal,
+        });
+    }
+}
+//# sourceMappingURL=Agent.js.map