@falai/agent 0.8.1 → 0.9.0-alpha-2

package/dist/src/core/Agent.js

@@ -0,0 +1,1656 @@
+/**
+ * Core Agent implementation
+ */
+import { EventKind, MessageRole } from "../types/history";
+import { enterRoute, enterStep, mergeCollected, logger, LoggerLevel, render, getLastMessageFromHistory, normalizeHistory, cloneDeep, } from "../utils";
+import { Route } from "./Route";
+import { Step } from "./Step";
+import { PersistenceManager } from "./PersistenceManager";
+import { SessionManager } from "./SessionManager";
+import { RoutingEngine } from "./RoutingEngine";
+import { ResponseEngine } from "./ResponseEngine";
+import { ToolExecutor } from "./ToolExecutor";
+import { ResponsePipeline } from "./ResponsePipeline";
+import { END_ROUTE_ID } from "../constants";
+/**
+ * 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 and response engines
+        this.routingEngine = new RoutingEngine({
+            maxCandidates: 5,
+            allowRouteSwitch: true,
+            switchThreshold: 70,
+        });
+        this.responseEngine = new ResponseEngine();
+        this.responsePipeline = new 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) {
+            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
+        this.session = new SessionManager(this.persistenceManager);
+        // Store sessionId for later use in getOrCreate calls
+        if (options.sessionId) {
+            // The session will be loaded on first getOrCreate call
+            this.session.getOrCreate(options.sessionId).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() {
+        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);
+        }
+        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.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;
+    }
+    /**
+     * Register a tool at the agent level
+     */
+    createTool(tool) {
+        this.tools.push(tool);
+        return this;
+    }
+    /**
+     * Register multiple tools at the agent level
+     */
+    registerTools(tools) {
+        tools.forEach((tool) => this.createTool(tool));
+        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) {
+        const { history: simpleHistory, signal } = params;
+        const history = normalizeHistory(simpleHistory);
+        // Prepare context and session using the response pipeline
+        this.responsePipeline.setContext(this.context);
+        this.responsePipeline.setCurrentSession(this.currentSession);
+        let session;
+        const responseContext = await this.responsePipeline.prepareResponseContext({
+            contextOverride: params.contextOverride,
+            session: params.session ? cloneDeep(params.session) : undefined,
+        });
+        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 = mergeCollected(session, this.collectedData);
+            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
+        if (session.currentRoute && session.currentStep) {
+            const currentRoute = this.routes.find((r) => r.id === session.currentRoute?.id);
+            if (currentRoute) {
+                const currentStep = currentRoute.getStep(session.currentStep.id);
+                if (currentStep?.prepare) {
+                    logger.debug(`[Agent] Executing prepare for step: ${currentStep.id}`);
+                    await this.executePrepareFinalize(currentStep.prepare, effectiveContext, session.data, currentRoute, currentStep);
+                }
+            }
+        }
+        // PHASE 2: ROUTING + STEP SELECTION - Use response pipeline
+        const routingResult = await this.responsePipeline.handleRoutingAndStepSelection({
+            session,
+            history,
+            context: effectiveContext,
+            signal,
+        });
+        const selectedRoute = routingResult.selectedRoute;
+        const selectedStep = routingResult.selectedStep;
+        const responseDirectives = routingResult.responseDirectives;
+        const isRouteComplete = routingResult.isRouteComplete;
+        session = routingResult.session;
+        // PHASE 3: DETERMINE NEXT STEP - Use pipeline method
+        const stepResult = this.responsePipeline.determineNextStep({
+            selectedRoute,
+            selectedStep,
+            session,
+            isRouteComplete,
+        });
+        const nextStep = stepResult.nextStep;
+        session = stepResult.session;
+        if (selectedRoute && !isRouteComplete) {
+            // PHASE 4: RESPONSE GENERATION - Stream message using selected route and step
+            // Get last user message
+            const lastUserMessage = getLastMessageFromHistory(history);
+            // Build response schema for this route (with collect fields from step)
+            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, nextStep, this.schema);
+            // Check if selected route and next step are defined
+            if (!selectedRoute || !nextStep) {
+                logger.error("[Agent] Selected route or next step is not defined", {
+                    selectedRoute,
+                    nextStep,
+                });
+                throw new Error("Selected route or next step is not defined");
+            }
+            // Build response prompt
+            const responsePrompt = await this.responseEngine.buildResponsePrompt({
+                route: selectedRoute,
+                currentStep: nextStep,
+                rules: selectedRoute.getRules(),
+                prohibitions: selectedRoute.getProhibitions(),
+                directives: responseDirectives,
+                history,
+                lastMessage: lastUserMessage,
+                agentOptions: this.options,
+                // Combine agent and route properties according to the specified logic
+                combinedGuidelines: [
+                    ...this.getGuidelines(),
+                    ...selectedRoute.getGuidelines(),
+                ],
+                combinedTerms: this.mergeTerms(this.getTerms(), selectedRoute.getTerms()),
+                context: effectiveContext,
+                session,
+                agentSchema: this.schema,
+            });
+            // Collect available tools for AI
+            const availableTools = this.collectAvailableTools(selectedRoute, nextStep);
+            // Generate message stream using AI provider
+            const stream = this.options.provider.generateMessageStream({
+                prompt: responsePrompt,
+                history,
+                context: effectiveContext,
+                tools: availableTools,
+                signal,
+                parameters: {
+                    jsonSchema: responseSchema,
+                    schemaName: "response_stream_output",
+                },
+            });
+            // Stream chunks to caller
+            for await (const chunk of stream) {
+                let toolCalls = undefined;
+                // Extract tool calls from AI response on final chunk
+                if (chunk.done && chunk.structured?.toolCalls) {
+                    toolCalls = chunk.structured.toolCalls;
+                    // Execute dynamic tool calls
+                    if (toolCalls.length > 0) {
+                        logger.debug(`[Agent] Executing ${toolCalls.length} dynamic tool calls`);
+                        for (const toolCall of toolCalls) {
+                            const tool = this.findAvailableTool(toolCall.toolName, selectedRoute);
+                            if (!tool) {
+                                logger.warn(`[Agent] Tool not found: ${toolCall.toolName}`);
+                                continue;
+                            }
+                            const toolExecutor = new ToolExecutor();
+                            const result = await toolExecutor.executeTool({
+                                tool: tool,
+                                context: effectiveContext,
+                                updateContext: this.updateContext.bind(this),
+                                updateData: this.updateCollectedData.bind(this),
+                                history,
+                                data: session.data,
+                                toolArguments: toolCall.arguments,
+                            });
+                            // Update context with tool results
+                            if (result.contextUpdate) {
+                                await this.updateContext(result.contextUpdate);
+                            }
+                            // Update collected data with tool results
+                            if (result.dataUpdate) {
+                                session = await this.updateData(session, result.dataUpdate);
+                                logger.debug(`[Agent] Tool updated collected data:`, result.dataUpdate);
+                            }
+                            logger.debug(`[Agent] Executed dynamic tool: ${result.toolName} (success: ${result.success})`);
+                        }
+                    }
+                }
+                // TOOL LOOP: Allow AI to make follow-up tool calls after initial tool execution (streaming)
+                const MAX_TOOL_LOOPS = 5;
+                let toolLoopCount = 0;
+                let hasToolCalls = toolCalls && toolCalls.length > 0;
+                while (hasToolCalls && toolLoopCount < MAX_TOOL_LOOPS) {
+                    toolLoopCount++;
+                    logger.debug(`[Agent] Starting streaming tool loop ${toolLoopCount}/${MAX_TOOL_LOOPS}`);
+                    // Add tool execution results to history so AI knows what happened
+                    const toolResultsEvents = [];
+                    for (const toolCall of toolCalls || []) {
+                        const tool = this.findAvailableTool(toolCall.toolName, selectedRoute);
+                        if (tool) {
+                            toolResultsEvents.push({
+                                kind: EventKind.TOOL,
+                                source: MessageRole.AGENT,
+                                timestamp: new Date().toISOString(),
+                                data: {
+                                    tool_calls: [
+                                        {
+                                            tool_id: toolCall.toolName,
+                                            arguments: toolCall.arguments,
+                                            result: {
+                                                data: "Tool executed successfully",
+                                            },
+                                        },
+                                    ],
+                                },
+                            });
+                        }
+                    }
+                    // Create updated history with tool results
+                    const updatedHistory = [...history, ...toolResultsEvents];
+                    // Make follow-up streaming AI call to see if more tools are needed
+                    const followUpStream = this.options.provider.generateMessageStream({
+                        prompt: responsePrompt,
+                        history: updatedHistory,
+                        context: effectiveContext,
+                        tools: availableTools,
+                        parameters: {
+                            jsonSchema: responseSchema,
+                            schemaName: "tool_followup",
+                        },
+                        signal,
+                    });
+                    let followUpToolCalls;
+                    for await (const followUpChunk of followUpStream) {
+                        // Extract tool calls from follow-up stream
+                        if (followUpChunk.done && followUpChunk.structured?.toolCalls) {
+                            followUpToolCalls = followUpChunk.structured.toolCalls;
+                        }
+                    }
+                    hasToolCalls = followUpToolCalls && followUpToolCalls.length > 0;
+                    if (hasToolCalls) {
+                        logger.debug(`[Agent] Follow-up streaming call produced ${followUpToolCalls.length} additional tool calls`);
+                        // Execute the follow-up tool calls
+                        for (const toolCall of followUpToolCalls) {
+                            const tool = this.findAvailableTool(toolCall.toolName, selectedRoute);
+                            if (!tool) {
+                                logger.warn(`[Agent] Tool not found in streaming follow-up: ${toolCall.toolName}`);
+                                continue;
+                            }
+                            const toolExecutor = new ToolExecutor();
+                            const result = await toolExecutor.executeTool({
+                                tool: tool,
+                                context: effectiveContext,
+                                updateContext: this.updateContext.bind(this),
+                                updateData: this.updateCollectedData.bind(this),
+                                history: updatedHistory,
+                                data: session.data,
+                                toolArguments: toolCall.arguments,
+                            });
+                            // Update context with follow-up tool results
+                            if (result.contextUpdate) {
+                                await this.updateContext(result.contextUpdate);
+                            }
+                            if (result.dataUpdate) {
+                                session = await this.updateData(session, result.dataUpdate);
+                                logger.debug(`[Agent] Streaming follow-up tool updated collected data:`, result.dataUpdate);
+                            }
+                            logger.debug(`[Agent] Executed streaming follow-up tool: ${result.toolName} (success: ${result.success})`);
+                        }
+                        // Update toolCalls for next iteration
+                        toolCalls = followUpToolCalls;
+                    }
+                    else {
+                        logger.debug(`[Agent] Streaming tool loop completed after ${toolLoopCount} iterations`);
+                        // Update toolCalls for final response
+                        toolCalls = followUpToolCalls || [];
+                        break;
+                    }
+                }
+                if (toolLoopCount >= MAX_TOOL_LOOPS) {
+                    logger.warn(`[Agent] Streaming tool loop limit reached (${MAX_TOOL_LOOPS}), stopping`);
+                }
+                // Extract collected data on final chunk
+                if (chunk.done && chunk.structured && nextStep.collect) {
+                    const collectedData = {};
+                    // The structured response includes both base fields and collected extraction fields
+                    const structuredData = chunk.structured;
+                    for (const field of nextStep.collect) {
+                        const fieldKey = String(field);
+                        if (fieldKey in structuredData) {
+                            collectedData[fieldKey] = structuredData[fieldKey];
+                        }
+                    }
+                    // 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);
+                        logger.debug(`[Agent] Collected data:`, collectedData);
+                    }
+                }
+                // Extract any additional data from structured response on final chunk
+                if (chunk.done &&
+                    chunk.structured &&
+                    typeof chunk.structured === "object" &&
+                    "contextUpdate" in chunk.structured) {
+                    await this.updateContext(chunk.structured
+                        .contextUpdate);
+                }
+                // Auto-save session step on final chunk
+                if (chunk.done &&
+                    this.persistenceManager &&
+                    session.id &&
+                    this.options.persistence?.autoSave !== false) {
+                    await this.persistenceManager.saveSessionState(session.id, session);
+                    logger.debug(`[Agent] Auto-saved session step to persistence: ${session.id}`);
+                }
+                // Execute finalize function on final chunk
+                if (chunk.done && session.currentRoute && session.currentStep) {
+                    const currentRoute = this.routes.find((r) => r.id === session.currentRoute?.id);
+                    if (currentRoute) {
+                        const currentStep = currentRoute.getStep(session.currentStep.id);
+                        if (currentStep?.finalize) {
+                            logger.debug(`[Agent] Executing finalize for step: ${currentStep.id}`);
+                            await this.executePrepareFinalize(currentStep.finalize, effectiveContext, session.data, currentRoute, currentStep);
+                        }
+                    }
+                }
+                // Update current session if we have one
+                if (chunk.done && this.currentSession) {
+                    this.currentSession = session;
+                }
+                yield {
+                    delta: chunk.delta,
+                    accumulated: chunk.accumulated,
+                    done: chunk.done,
+                    session, // Return updated session
+                    toolCalls,
+                    isRouteComplete,
+                    metadata: chunk.metadata,
+                    structured: chunk.structured,
+                };
+            }
+        }
+        else if (isRouteComplete && selectedRoute) {
+            // Route is complete - generate completion message then check for onComplete transition
+            const lastUserMessage = getLastMessageFromHistory(history);
+            // Get endStep spec from route
+            const endStepSpec = selectedRoute.endStepSpec;
+            // Create a temporary step for completion message generation using endStep configuration
+            const completionStep = new Step(selectedRoute.id, {
+                description: endStepSpec.description,
+                id: endStepSpec.id || END_ROUTE_ID,
+                collect: endStepSpec.collect,
+                requires: endStepSpec.requires,
+                prompt: endStepSpec.prompt ||
+                    "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, this.schema);
+            const templateContext = {
+                context: effectiveContext,
+                session,
+                history,
+            };
+            // Build completion response prompt
+            const completionPrompt = await this.responseEngine.buildResponsePrompt({
+                route: selectedRoute,
+                currentStep: completionStep,
+                rules: selectedRoute.getRules(),
+                prohibitions: selectedRoute.getProhibitions(),
+                directives: undefined, // No directives for completion
+                history,
+                lastMessage: lastUserMessage,
+                agentOptions: this.options,
+                // Combine agent and route properties according to the specified logic
+                combinedGuidelines: [
+                    ...this.getGuidelines(),
+                    ...selectedRoute.getGuidelines(),
+                ],
+                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({
+                prompt: completionPrompt,
+                history,
+                context: effectiveContext,
+                signal,
+                parameters: {
+                    jsonSchema: responseSchema,
+                    schemaName: "completion_message_stream",
+                },
+            });
+            logger.debug(`[Agent] Streaming completion message for route: ${selectedRoute.title}`);
+            // Check for onComplete transition
+            const transitionConfig = await selectedRoute.evaluateOnComplete({ data: session.data }, effectiveContext);
+            if (transitionConfig) {
+                // Find target route by ID or title
+                const targetRoute = this.routes.find((r) => r.id === transitionConfig.nextStep ||
+                    r.title === transitionConfig.nextStep);
+                if (targetRoute) {
+                    const renderedCondition = await render(transitionConfig.condition, templateContext);
+                    // Set pending transition in session
+                    session = {
+                        ...session,
+                        pendingTransition: {
+                            targetRouteId: targetRoute.id,
+                            condition: renderedCondition,
+                            reason: "route_complete",
+                        },
+                    };
+                    logger.debug(`[Agent] Route ${selectedRoute.title} completed with pending transition to: ${targetRoute.title}`);
+                }
+                else {
+                    logger.warn(`[Agent] Route ${selectedRoute.title} completed but target route not found: ${transitionConfig.nextStep}`);
+                }
+            }
+            // Set step to END_ROUTE marker
+            session = enterStep(session, END_ROUTE_ID, "Route completed");
+            logger.debug(`[Agent] Route ${selectedRoute.title} completed. Entered END_ROUTE step.`);
+            // Stream completion chunks
+            for await (const chunk of stream) {
+                // Update current session if we have one
+                if (chunk.done && this.currentSession) {
+                    this.currentSession = session;
+                }
+                yield {
+                    delta: chunk.delta,
+                    accumulated: chunk.accumulated,
+                    done: chunk.done,
+                    session,
+                    toolCalls: undefined,
+                    isRouteComplete: true,
+                    metadata: chunk.metadata,
+                    structured: chunk.structured,
+                };
+            }
+        }
+        else {
+            // Fallback: No routes defined, stream a simple response
+            const fallbackPrompt = await this.responseEngine.buildFallbackPrompt({
+                history,
+                agentOptions: this.options,
+                terms: this.terms,
+                guidelines: this.guidelines,
+                context: effectiveContext,
+                session,
+            });
+            const stream = this.options.provider.generateMessageStream({
+                prompt: fallbackPrompt,
+                history,
+                context: effectiveContext,
+                signal,
+                parameters: {
+                    jsonSchema: {
+                        type: "object",
+                        properties: {
+                            message: { type: "string" },
+                        },
+                        required: ["message"],
+                        additionalProperties: false,
+                    },
+                    schemaName: "fallback_stream_response",
+                },
+            });
+            for await (const chunk of stream) {
+                // Update current session if we have one
+                if (chunk.done && this.currentSession) {
+                    this.currentSession = session;
+                }
+                yield {
+                    delta: chunk.delta,
+                    accumulated: chunk.accumulated,
+                    done: chunk.done,
+                    session, // Return updated session
+                    toolCalls: undefined,
+                    isRouteComplete: false,
+                    metadata: chunk.metadata,
+                    structured: chunk.structured,
+                };
+            }
+        }
+    }
+    /**
+     * Generate a response based on history and context
+     */
+    async respond(params) {
+        const { history: simpleHistory, contextOverride, signal } = params;
+        const history = normalizeHistory(simpleHistory);
+        // Get current context (may fetch from provider)
+        let currentContext = await this.getContext();
+        // Call beforeRespond hook if configured
+        if (this.options.hooks?.beforeRespond && currentContext !== undefined) {
+            currentContext = await this.options.hooks.beforeRespond(currentContext);
+            // Update stored context with the result from beforeRespond
+            this.context = currentContext;
+        }
+        // Merge context with override
+        const effectiveContext = {
+            ...currentContext,
+            ...contextOverride,
+        };
+        // Initialize or get session (use current session if available)
+        let session = cloneDeep(params.session) ||
+            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 = mergeCollected(session, this.collectedData);
+            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);
+            if (currentRoute) {
+                const currentStep = currentRoute.getStep(session.currentStep.id);
+                if (currentStep?.prepare) {
+                    logger.debug(`[Agent] Executing prepare for step: ${currentStep.id}`);
+                    await this.executePrepareFinalize(currentStep.prepare, effectiveContext, session.data, currentRoute, currentStep);
+                }
+            }
+        }
+        // PHASE 2: ROUTING + STEP SELECTION - Determine which route and step to use (combined)
+        let selectedRoute;
+        let responseDirectives;
+        let selectedStep;
+        let isRouteComplete = false;
+        // Check for pending transition from previous route completion
+        if (session.pendingTransition) {
+            const targetRoute = this.routes.find((r) => r.id === session.pendingTransition?.targetRouteId);
+            if (targetRoute) {
+                logger.debug(`[Agent] Auto-transitioning from pending transition to route: ${targetRoute.title}`);
+                // Clear pending transition and enter new route
+                session = {
+                    ...session,
+                    pendingTransition: undefined,
+                };
+                session = enterRoute(session, targetRoute.id, targetRoute.title);
+                // Merge initial data if available
+                if (targetRoute.initialData) {
+                    session = mergeCollected(session, targetRoute.initialData);
+                }
+                selectedRoute = targetRoute;
+            }
+            else {
+                logger.warn(`[Agent] Pending transition target route not found: ${session.pendingTransition.targetRouteId}`);
+                // Clear invalid transition
+                session = {
+                    ...session,
+                    pendingTransition: undefined,
+                };
+            }
+        }
+        // If no pending transition or transition handled, do normal routing
+        if (this.routes.length > 0 && !selectedRoute) {
+            const orchestration = await this.routingEngine.decideRouteAndStep({
+                routes: this.routes,
+                session,
+                history,
+                agentOptions: this.options,
+                provider: this.options.provider,
+                context: effectiveContext,
+                signal,
+            });
+            selectedRoute = orchestration.selectedRoute;
+            selectedStep = orchestration.selectedStep;
+            responseDirectives = orchestration.responseDirectives;
+            session = orchestration.session;
+            isRouteComplete = orchestration.isRouteComplete || false;
+            // Log if route is complete
+            if (isRouteComplete) {
+                logger.debug(`[Agent] Route complete: all required data collected, END_ROUTE reached`);
+            }
+        }
+        // PHASE 3: DETERMINE NEXT STEP - Use step from combined decision or get initial step
+        let message;
+        let toolCalls = undefined;
+        let responsePrompt;
+        let availableTools = [];
+        let responseSchema;
+        let nextStep;
+        // Get last user message (needed for both route and completion handling)
+        const lastUserMessage = getLastMessageFromHistory(history);
+        if (selectedRoute && !isRouteComplete) {
+            // If we have a selected step from the combined routing decision, use it
+            if (selectedStep) {
+                nextStep = selectedStep;
+            }
+            else {
+                // New route or no step selected - get initial step or first valid step
+                const candidates = this.routingEngine.getCandidateSteps(selectedRoute, undefined, session.data || {});
+                if (candidates.length > 0) {
+                    nextStep = candidates[0].step;
+                    logger.debug(`[Agent] Using first valid step: ${nextStep.id} for new route`);
+                }
+                else {
+                    // Fallback to initial step even if it should be skipped
+                    nextStep = selectedRoute.initialStep;
+                    logger.warn(`[Agent] No valid steps found, using initial step: ${nextStep.id}`);
+                }
+            }
+            // Update session with next step
+            session = enterStep(session, nextStep.id, nextStep.description);
+            logger.debug(`[Agent] Entered step: ${nextStep.id}`);
+            // PHASE 4: RESPONSE GENERATION - Generate message using selected route and step
+            // Get last user message
+            const lastUserMessage = getLastMessageFromHistory(history);
+            // Build response schema for this route (with collect fields from step)
+            responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, nextStep, this.schema);
+            // Build response prompt
+            responsePrompt = await this.responseEngine.buildResponsePrompt({
+                route: selectedRoute,
+                currentStep: nextStep,
+                rules: selectedRoute.getRules(),
+                prohibitions: selectedRoute.getProhibitions(),
+                directives: responseDirectives,
+                history,
+                lastMessage: lastUserMessage,
+                agentOptions: this.options,
+                // Combine agent and route properties according to the specified logic
+                combinedGuidelines: [
+                    ...this.getGuidelines(),
+                    ...selectedRoute.getGuidelines(),
+                ],
+                combinedTerms: this.mergeTerms(this.getTerms(), selectedRoute.getTerms()),
+                context: effectiveContext,
+                session,
+                agentSchema: this.schema,
+            });
+            // Collect available tools for AI
+            availableTools = this.collectAvailableTools(selectedRoute, nextStep);
+        }
+        else {
+            // No route selected - generate basic response without route context
+            logger.debug(`[Agent] No route selected, generating basic response`);
+            // Build basic response prompt without route context
+            responsePrompt = await this.responseEngine.buildFallbackPrompt({
+                history,
+                agentOptions: this.options,
+                terms: this.getTerms(),
+                guidelines: this.getGuidelines(),
+                context: effectiveContext,
+                session,
+            });
+            // Use agent-level tools only
+            availableTools = this.collectAvailableTools();
+            responseSchema = undefined;
+        }
+        // Generate message using AI provider (common for both route and no-route cases)
+        const result = await this.options.provider.generateMessage({
+            prompt: responsePrompt,
+            history,
+            context: effectiveContext,
+            tools: availableTools,
+            signal,
+            parameters: responseSchema
+                ? {
+                    jsonSchema: responseSchema,
+                    schemaName: "response_output",
+                }
+                : undefined,
+        });
+        message = result.structured?.message || result.message;
+        // Process dynamic tool calls from AI response (common for both route and no-route cases)
+        if (result.structured?.toolCalls) {
+            toolCalls = result.structured.toolCalls;
+            // Execute dynamic tool calls
+            if (toolCalls.length > 0) {
+                logger.debug(`[Agent] Executing ${toolCalls.length} dynamic tool calls`);
+                for (const toolCall of toolCalls) {
+                    const tool = this.findAvailableTool(toolCall.toolName, selectedRoute);
+                    if (!tool) {
+                        logger.warn(`[Agent] Tool not found: ${toolCall.toolName}`);
+                        continue;
+                    }
+                    const toolExecutor = new ToolExecutor();
+                    const toolResult = await toolExecutor.executeTool({
+                        tool: tool,
+                        context: effectiveContext,
+                        updateContext: this.updateContext.bind(this),
+                        updateData: this.updateCollectedData.bind(this),
+                        history,
+                        data: session.data,
+                        toolArguments: toolCall.arguments,
+                    });
+                    // Update context with tool results
+                    if (toolResult.contextUpdate) {
+                        await this.updateContext(toolResult.contextUpdate);
+                    }
+                    // Update collected data with tool results
+                    if (toolResult.dataUpdate) {
+                        session = await this.updateData(session, toolResult.dataUpdate);
+                        logger.debug(`[Agent] Tool updated collected data:`, toolResult.dataUpdate);
+                    }
+                    logger.debug(`[Agent] Executed dynamic tool: ${toolResult.toolName} (success: ${toolResult.success})`);
+                }
+            }
+        }
+        // TOOL LOOP: Allow AI to make follow-up tool calls after initial tool execution
+        const MAX_TOOL_LOOPS = 5;
+        let toolLoopCount = 0;
+        let hasToolCalls = toolCalls && toolCalls.length > 0;
+        while (hasToolCalls && toolLoopCount < MAX_TOOL_LOOPS) {
+            toolLoopCount++;
+            logger.debug(`[Agent] Starting tool loop ${toolLoopCount}/${MAX_TOOL_LOOPS}`);
+            // Add tool execution results to history so AI knows what happened
+            const toolResultsEvents = [];
+            for (const toolCall of toolCalls || []) {
+                const tool = this.findAvailableTool(toolCall.toolName, selectedRoute);
+                if (tool) {
+                    toolResultsEvents.push({
+                        kind: EventKind.TOOL,
+                        source: MessageRole.AGENT,
+                        timestamp: new Date().toISOString(),
+                        data: {
+                            tool_calls: [
+                                {
+                                    tool_id: toolCall.toolName,
+                                    arguments: toolCall.arguments,
+                                    result: {
+                                        data: "Tool executed successfully",
+                                    },
+                                },
+                            ],
+                        },
+                    });
+                }
+            }
+            // Create updated history with tool results
+            const updatedHistory = [...history, ...toolResultsEvents];
+            // Make follow-up AI call to see if more tools are needed
+            const followUpResult = await this.options.provider.generateMessage({
+                prompt: responsePrompt,
+                history: updatedHistory,
+                context: effectiveContext,
+                tools: availableTools,
+                parameters: {
+                    jsonSchema: responseSchema,
+                    schemaName: "tool_followup",
+                },
+                signal,
+            });
+            // Check if follow-up call has more tool calls
+            const followUpToolCalls = followUpResult.structured?.toolCalls;
+            hasToolCalls = followUpToolCalls && followUpToolCalls.length > 0;
+            if (hasToolCalls) {
+                logger.debug(`[Agent] Follow-up call produced ${followUpToolCalls.length} additional tool calls`);
+                // Execute the follow-up tool calls
+                for (const toolCall of followUpToolCalls) {
+                    const tool = this.findAvailableTool(toolCall.toolName, selectedRoute);
+                    if (!tool) {
+                        logger.warn(`[Agent] Tool not found in follow-up: ${toolCall.toolName}`);
+                        continue;
+                    }
+                    const toolExecutor = new ToolExecutor();
+                    const toolResult = await toolExecutor.executeTool({
+                        tool: tool,
+                        context: effectiveContext,
+                        updateContext: this.updateContext.bind(this),
+                        updateData: this.updateCollectedData.bind(this),
+                        history: updatedHistory,
+                        data: session.data,
+                        toolArguments: toolCall.arguments,
+                    });
+                    // Update context with follow-up tool results
+                    if (toolResult.contextUpdate) {
+                        await this.updateContext(toolResult.contextUpdate);
+                    }
+                    if (toolResult.dataUpdate) {
+                        session = await this.updateData(session, toolResult.dataUpdate);
+                        logger.debug(`[Agent] Follow-up tool updated collected data:`, toolResult.dataUpdate);
+                    }
+                    logger.debug(`[Agent] Executed follow-up tool: ${toolResult.toolName} (success: ${toolResult.success})`);
+                }
+                // Update toolCalls for next iteration or final response
+                toolCalls = followUpToolCalls;
+            }
+            else {
+                logger.debug(`[Agent] Tool loop completed after ${toolLoopCount} iterations`);
+                // Update final message and toolCalls from follow-up result if no more tools
+                message = followUpResult.structured?.message || followUpResult.message;
+                toolCalls = followUpToolCalls || [];
+                break;
+            }
+        }
+        if (toolLoopCount >= MAX_TOOL_LOOPS) {
+            logger.warn(`[Agent] Tool loop limit reached (${MAX_TOOL_LOOPS}), stopping`);
+        }
+        // Extract collected data from final response (only for route-based interactions)
+        if (selectedRoute && result.structured && nextStep?.collect) {
+            const collectedData = {};
+            // The structured response includes both base fields and collected extraction fields
+            const structuredData = result.structured;
+            for (const field of nextStep.collect) {
+                const fieldKey = String(field);
+                if (fieldKey in structuredData) {
+                    collectedData[fieldKey] = structuredData[fieldKey];
+                }
+            }
+            // 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);
+                logger.debug(`[Agent] Collected data:`, collectedData);
+            }
+        }
+        // Extract any additional data from structured response
+        if (result.structured &&
+            typeof result.structured === "object" &&
+            "contextUpdate" in result.structured) {
+            await this.updateContext(result.structured
+                .contextUpdate);
+        }
+        // Handle route completion if route is complete
+        if (isRouteComplete) {
+            // Route is complete - generate completion message then check for onComplete transition
+            // Get endStep spec from route
+            const endStepSpec = selectedRoute.endStepSpec;
+            // Create a temporary step for completion message generation using endStep configuration
+            const completionStep = new Step(selectedRoute.id, {
+                description: endStepSpec.description,
+                id: endStepSpec.id || END_ROUTE_ID,
+                collect: endStepSpec.collect,
+                requires: endStepSpec.requires,
+                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, this.schema);
+            const templateContext = {
+                context: effectiveContext,
+                session,
+                history,
+            };
+            // Build completion response prompt
+            const completionPrompt = await this.responseEngine.buildResponsePrompt({
+                route: selectedRoute,
+                currentStep: completionStep,
+                rules: selectedRoute.getRules(),
+                prohibitions: selectedRoute.getProhibitions(),
+                directives: undefined, // No directives for completion
+                history,
+                lastMessage: lastUserMessage,
+                agentOptions: this.options,
+                // Combine agent and route properties according to the specified logic
+                combinedGuidelines: [
+                    ...this.getGuidelines(),
+                    ...selectedRoute.getGuidelines(),
+                ],
+                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({
+                prompt: completionPrompt,
+                history,
+                context: effectiveContext,
+                signal,
+                parameters: {
+                    jsonSchema: responseSchema,
+                    schemaName: "completion_message",
+                },
+            });
+            message =
+                completionResult.structured?.message || completionResult.message;
+            logger.debug(`[Agent] Generated completion message for route: ${selectedRoute.title}`);
+            // Check for onComplete transition
+            const transitionConfig = await selectedRoute.evaluateOnComplete({ data: session.data }, effectiveContext);
+            if (transitionConfig) {
+                // Find target route by ID or title
+                const targetRoute = this.routes.find((r) => r.id === transitionConfig.nextStep ||
+                    r.title === transitionConfig.nextStep);
+                if (targetRoute) {
+                    const renderedCondition = await render(transitionConfig.condition, templateContext);
+                    // Set pending transition in session
+                    session = {
+                        ...session,
+                        pendingTransition: {
+                            targetRouteId: targetRoute.id,
+                            condition: renderedCondition,
+                            reason: "route_complete",
+                        },
+                    };
+                    logger.debug(`[Agent] Route ${selectedRoute.title} completed with pending transition to: ${targetRoute.title}`);
+                }
+                else {
+                    logger.warn(`[Agent] Route ${selectedRoute.title} completed but target route not found: ${transitionConfig.nextStep}`);
+                }
+            }
+            // Set step to END_ROUTE marker
+            session = enterStep(session, END_ROUTE_ID, "Route completed");
+            logger.debug(`[Agent] Route ${selectedRoute.title} completed. Entered END_ROUTE step.`);
+        }
+        else {
+            // Fallback: No routes defined, generate a simple response
+            const fallbackPrompt = await this.responseEngine.buildFallbackPrompt({
+                history,
+                agentOptions: this.options,
+                terms: this.terms,
+                guidelines: this.guidelines,
+                context: effectiveContext,
+                session,
+            });
+            const result = await this.options.provider.generateMessage({
+                prompt: fallbackPrompt,
+                history,
+                context: effectiveContext,
+                signal,
+                parameters: {
+                    jsonSchema: {
+                        type: "object",
+                        properties: {
+                            message: { type: "string" },
+                        },
+                        required: ["message"],
+                        additionalProperties: false,
+                    },
+                    schemaName: "fallback_response",
+                },
+            });
+            message = result.structured?.message || result.message;
+        }
+        // Auto-save session step to persistence if configured
+        if (this.persistenceManager &&
+            session.id &&
+            this.options.persistence?.autoSave !== false) {
+            await this.persistenceManager.saveSessionState(session.id, session);
+            logger.debug(`[Agent] Auto-saved session step to persistence: ${session.id}`);
+        }
+        // Execute finalize function
+        if (session.currentRoute && session.currentStep) {
+            const currentRoute = this.routes.find((r) => r.id === session.currentRoute?.id);
+            if (currentRoute) {
+                const currentStep = currentRoute.getStep(session.currentStep.id);
+                if (currentStep?.finalize) {
+                    logger.debug(`[Agent] Executing finalize for step: ${currentStep.id}`);
+                    await this.executePrepareFinalize(currentStep.finalize, effectiveContext, session.data, currentRoute, currentStep);
+                }
+            }
+        }
+        // Update current session if we have one
+        if (this.currentSession) {
+            this.currentSession = session;
+        }
+        return {
+            message,
+            session, // Return updated session with route/step info
+            toolCalls,
+            isRouteComplete, // Indicates if the route has reached END_ROUTE with all data collected
+        };
+    }
+    /**
+     * Get all routes
+     */
+    getRoutes() {
+        return [...this.routes];
+    }
+    /**
+     * Get all terms
+     */
+    getTerms() {
+        return [...this.terms];
+    }
+    /**
+     * Get all tools
+     */
+    getTools() {
+        return [...this.tools];
+    }
+    /**
+     * Find an available tool by name for the given route
+     * Route-level tools take precedence over agent-level tools
+     * @private
+     */
+    findAvailableTool(toolName, route) {
+        // Check route-level tools first (if route provided)
+        if (route) {
+            const routeTool = route
+                .getTools()
+                .find((tool) => tool.id === toolName || tool.name === toolName);
+            if (routeTool)
+                return routeTool;
+        }
+        // Fall back to agent-level tools
+        return this.tools.find((tool) => tool.id === toolName || tool.name === toolName);
+    }
+    /**
+     * Collect all available tools for the given route and step context
+     * @private
+     */
+    collectAvailableTools(route, step) {
+        const availableTools = new Map();
+        // Add agent-level tools
+        this.tools.forEach((tool) => {
+            availableTools.set(tool.id, tool);
+        });
+        // Add route-level tools (these take precedence)
+        if (route) {
+            route.getTools().forEach((tool) => {
+                availableTools.set(tool.id, tool);
+            });
+        }
+        // Filter by step-level allowed tools if specified
+        if (step?.tools) {
+            const allowedToolIds = new Set();
+            const stepTools = [];
+            for (const toolRef of step.tools) {
+                if (typeof toolRef === "string") {
+                    // Reference to registered tool
+                    allowedToolIds.add(toolRef);
+                }
+                else {
+                    // Inline tool definition
+                    if (toolRef.id) {
+                        allowedToolIds.add(toolRef.id);
+                        stepTools.push(toolRef);
+                    }
+                }
+            }
+            // If step specifies tools, only include those
+            if (allowedToolIds.size > 0) {
+                const filteredTools = new Map();
+                for (const toolId of allowedToolIds) {
+                    const tool = availableTools.get(toolId);
+                    if (tool) {
+                        filteredTools.set(toolId, tool);
+                    }
+                }
+                // Add inline tools
+                stepTools.forEach((tool) => {
+                    if (tool.id) {
+                        filteredTools.set(tool.id, tool);
+                    }
+                });
+                availableTools.clear();
+                filteredTools.forEach((tool, id) => availableTools.set(id, tool));
+            }
+        }
+        // Convert to the format expected by AI providers
+        return Array.from(availableTools.values()).map((tool) => ({
+            id: tool.id,
+            name: tool.name || tool.id,
+            description: tool.description,
+            parameters: tool.parameters,
+        }));
+    }
+    /**
+     * Execute a prepare or finalize function/tool
+     * @private
+     */
+    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 - find it in available tools
+                const availableTools = new Map();
+                // Add agent-level tools
+                this.tools.forEach((t) => {
+                    availableTools.set(t.id, t);
+                });
+                // Add route-level tools
+                if (route) {
+                    route.getTools().forEach((t) => {
+                        availableTools.set(t.id, t);
+                    });
+                }
+                // Add step-level tools
+                if (step?.tools) {
+                    for (const toolRef of step.tools) {
+                        if (typeof toolRef === "string") {
+                            // Keep as is
+                        }
+                        else if (toolRef.id) {
+                            availableTools.set(toolRef.id, toolRef);
+                        }
+                    }
+                }
+                tool = availableTools.get(prepareOrFinalize);
+            }
+            else {
+                // Tool object - use directly
+                tool = prepareOrFinalize;
+            }
+            if (tool) {
+                const toolExecutor = new ToolExecutor();
+                const result = await toolExecutor.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"}`);
+            }
+        }
+    }
+    /**
+     * Get all guidelines
+     */
+    getGuidelines() {
+        return [...this.guidelines];
+    }
+    /**
+     * Get the agent's knowledge base
+     */
+    getKnowledgeBase() {
+        return { ...this.knowledgeBase };
+    }
+    /**
+     * Merge terms with route-specific taking precedence on conflicts
+     * @private
+     */
+    mergeTerms(agentTerms, routeTerms) {
+        const merged = new Map();
+        // Add agent terms first
+        agentTerms.forEach((term) => {
+            const name = typeof term.name === "string" ? term.name : term.name.toString();
+            merged.set(name, term);
+        });
+        // Add route terms (these take precedence)
+        routeTerms.forEach((term) => {
+            const name = typeof term.name === "string" ? term.name : term.name.toString();
+            merged.set(name, term);
+        });
+        return Array.from(merged.values());
+    }
+    /**
+     * 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;
+    }
+    /**
+     * Clear the current session
+     */
+    clearCurrentSession() {
+        this.currentSession = undefined;
+    }
+    /**
+     * 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() {
+        // 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 = {
+            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) {
+        // Determine which history to use
+        let history;
+        if (options?.history) {
+            // Use provided history for this response only
+            history = options.history;
+        }
+        else {
+            // Add user message to session history if provided
+            if (message) {
+                await this.session.addMessage("user", message);
+            }
+            history = this.session.getHistory();
+        }
+        // Get or create session
+        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 = mergeCollected(session, this.collectedData);
+            // Update the session manager with the merged data
+            await this.session.setData(this.collectedData);
+            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,
+            session,
+            contextOverride: options?.contextOverride,
+            signal: options?.signal,
+        });
+        // Add agent response to session history (only if not using override history)
+        if (!options?.history) {
+            await this.session.addMessage("assistant", result.message);
+        }
+        // Ensure the result includes the current session
+        return {
+            ...result,
+            session: result.session || this.session.current,
+        };
+    }
+}
+//# sourceMappingURL=Agent.js.map