@falai/agent 0.6.9 → 0.7.0

package/dist/core/Agent.js

@@ -1,18 +1,18 @@
 /**
  * Core Agent implementation
  */
-import { createSession, enterRoute, enterState, mergeExtracted } from "../types/session";
+import { createSession, enterRoute, enterStep, mergeCollected, } from "../types/session";
 import { PromptComposer } from "./PromptComposer";
 import { logger, LoggerLevel } from "../utils/logger";
 import { Route } from "./Route";
-import { State } from "./State";
+import { Step } from "./Step";
 import { DomainRegistry } from "./DomainRegistry";
 import { PersistenceManager } from "./PersistenceManager";
 import { RoutingEngine } from "./RoutingEngine";
 import { ResponseEngine } from "./ResponseEngine";
 import { ToolExecutor } from "./ToolExecutor";
 import { getLastMessageFromHistory } from "../utils/event";
-import { END_STATE_ID } from "../constants";
+import { END_ROUTE_ID } from "../constants";
 /**
  * Main Agent class with generic context support
  */
@@ -98,7 +98,7 @@ export class Agent {
     }
     /**
      * Create a new route (journey)
-     * @template TExtracted - Type of data extracted throughout the route
+     * @template TData - Type of data collected throughout the route
      */
     createRoute(options) {
         const route = new Route(options);
@@ -175,23 +175,23 @@ export class Agent {
         }
     }
     /**
-     * Update extracted data in session with lifecycle hook support
-     * Triggers the onExtractedUpdate lifecycle hook if configured
+     * Update collected data in session with lifecycle hook support
+     * Triggers the onDataUpdate lifecycle hook if configured
      * @internal
      */
-    async updateExtracted(session, extractedUpdate) {
-        const previousExtracted = { ...session.extracted };
-        // Merge new extracted data
-        let newExtracted = {
-            ...session.extracted,
-            ...extractedUpdate,
+    async updateData(session, collectedUpdate) {
+        const previousCollected = { ...session.data };
+        // Merge new collected data
+        let newCollected = {
+            ...session.data,
+            ...collectedUpdate,
         };
         // Trigger lifecycle hook if configured
-        if (this.options.hooks?.onExtractedUpdate) {
-            newExtracted = (await this.options.hooks.onExtractedUpdate(newExtracted, previousExtracted));
+        if (this.options.hooks?.onDataUpdate) {
+            newCollected = (await this.options.hooks.onDataUpdate(newCollected, previousCollected));
         }
         // Return updated session
-        return mergeExtracted(session, newExtracted);
+        return mergeCollected(session, newCollected);
     }
     /**
      * Get current context (fetches from provider if configured)
@@ -225,37 +225,37 @@ export class Agent {
         };
         // Initialize or get session (use current session if available)
         let session = params.session || this.currentSession || createSession();
-        // PHASE 1: TOOL EXECUTION - Execute tools if current state has toolState
-        if (session.currentRoute && session.currentState) {
+        // PHASE 1: TOOL EXECUTION - Execute tools if current step has tool
+        if (session.currentRoute && session.currentStep) {
             const currentRoute = this.routes.find((r) => r.id === session.currentRoute?.id);
             if (currentRoute) {
-                const currentState = currentRoute.getState(session.currentState.id);
-                if (currentState) {
-                    const transitions = currentState.getTransitions();
-                    const toolTransition = transitions.find((t) => t.spec.toolState);
-                    if (toolTransition?.spec.toolState) {
+                const currentStep = currentRoute.getStep(session.currentStep.id);
+                if (currentStep) {
+                    const transitions = currentStep.getTransitions();
+                    const toolTransition = transitions.find((t) => t.spec.tool);
+                    if (toolTransition?.spec.tool) {
                         const toolExecutor = new ToolExecutor();
                         // Get allowed domains from current route for security enforcement
                         const allowedDomains = currentRoute.getDomains();
-                        const result = await toolExecutor.executeTool(toolTransition.spec.toolState, effectiveContext, this.updateContext.bind(this), history, session.extracted, allowedDomains);
+                        const result = await toolExecutor.executeTool(toolTransition.spec.tool, effectiveContext, this.updateContext.bind(this), history, session.data, allowedDomains);
                         // Update context with tool results
                         if (result.contextUpdate) {
                             await this.updateContext(result.contextUpdate);
                         }
-                        // Update extracted data with tool results
-                        if (result.extractedUpdate) {
-                            session = await this.updateExtracted(session, result.extractedUpdate);
-                            logger.debug(`[Agent] Tool updated extracted data:`, result.extractedUpdate);
+                        // Update collected data with tool results
+                        if (result.collectedUpdate) {
+                            session = await this.updateData(session, result.collectedUpdate);
+                            logger.debug(`[Agent] Tool updated collected data:`, result.collectedUpdate);
                         }
                         logger.debug(`[Agent] Executed tool: ${result.toolName} (success: ${result.success})`);
                     }
                 }
             }
         }
-        // PHASE 2: ROUTING + STATE SELECTION - Determine which route and state to use (combined)
+        // PHASE 2: ROUTING + STEP SELECTION - Determine which route and step to use (combined)
         let selectedRoute;
         let responseDirectives;
-        let selectedState;
+        let selectedStep;
         let isRouteComplete = false;
         // Check for pending transition from previous route completion
         if (session.pendingTransition) {
@@ -270,7 +270,7 @@ export class Agent {
                 session = enterRoute(session, targetRoute.id, targetRoute.title);
                 // Merge initial data if available
                 if (targetRoute.initialData) {
-                    session = mergeExtracted(session, targetRoute.initialData);
+                    session = mergeCollected(session, targetRoute.initialData);
                 }
                 selectedRoute = targetRoute;
             }
@@ -285,7 +285,7 @@ export class Agent {
         }
         // If no pending transition or transition handled, do normal routing
         if (this.routes.length > 0 && !selectedRoute) {
-            const orchestration = await this.routingEngine.decideRouteAndState({
+            const orchestration = await this.routingEngine.decideRouteAndStep({
                 routes: this.routes,
                 session,
                 history,
@@ -300,45 +300,45 @@ export class Agent {
                 signal,
             });
             selectedRoute = orchestration.selectedRoute;
-            selectedState = orchestration.selectedState;
+            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_STATE reached`);
+                logger.debug(`[Agent] Route complete: all required data collected, END_ROUTE reached`);
             }
         }
-        // PHASE 3: DETERMINE NEXT STATE - Use state from combined decision or get initial state
+        // PHASE 3: DETERMINE NEXT STEP - Use step from combined decision or get initial step
         if (selectedRoute && !isRouteComplete) {
-            let nextState;
-            // If we have a selected state from the combined routing decision, use it
-            if (selectedState) {
-                nextState = selectedState;
+            let nextStep;
+            // If we have a selected step from the combined routing decision, use it
+            if (selectedStep) {
+                nextStep = selectedStep;
             }
             else {
-                // New route or no state selected - get initial state or first valid state
-                const candidates = this.routingEngine.getCandidateStates(selectedRoute, undefined, session.extracted || {});
+                // 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) {
-                    nextState = candidates[0].state;
-                    logger.debug(`[Agent] Using first valid state: ${nextState.id} for new route`);
+                    nextStep = candidates[0].step;
+                    logger.debug(`[Agent] Using first valid step: ${nextStep.id} for new route`);
                 }
                 else {
-                    // Fallback to initial state even if it should be skipped
-                    nextState = selectedRoute.initialState;
-                    logger.warn(`[Agent] No valid states found, using initial state: ${nextState.id}`);
+                    // 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 state
-            session = enterState(session, nextState.id, nextState.description);
-            logger.debug(`[Agent] Entered state: ${nextState.id}`);
-            // PHASE 4: RESPONSE GENERATION - Stream message using selected route and state
+            // Update session with next step
+            session = enterStep(session, nextStep.id, nextStep.description);
+            logger.debug(`[Agent] Entered step: ${nextStep.id}`);
+            // 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 gather fields from state)
-            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, nextState);
+            // Build response schema for this route (with collect fields from step)
+            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, nextStep);
             // Build response prompt
-            const responsePrompt = this.responseEngine.buildResponsePrompt(selectedRoute, nextState, selectedRoute.getRules(), selectedRoute.getProhibitions(), responseDirectives, history, lastUserMessage, {
+            const responsePrompt = this.responseEngine.buildResponsePrompt(selectedRoute, nextStep, selectedRoute.getRules(), selectedRoute.getProhibitions(), responseDirectives, history, lastUserMessage, {
                 name: this.options.name,
                 goal: this.options.goal,
                 description: this.options.description,
@@ -358,20 +358,20 @@ export class Agent {
             // Stream chunks to caller
             for await (const chunk of stream) {
                 const toolCalls = undefined;
-                // Extract gathered data on final chunk
-                if (chunk.done && chunk.structured && nextState.gatherFields) {
-                    const gatheredData = {};
-                    // The structured response includes both base fields and gathered extraction fields
+                // Extract collected data on final chunk
+                if (chunk.done && chunk.structured && nextStep.collectFields) {
+                    const collectedData = {};
+                    // The structured response includes both base fields and collected extraction fields
                     const structuredData = chunk.structured;
-                    for (const field of nextState.gatherFields) {
+                    for (const field of nextStep.collectFields) {
                         if (field in structuredData) {
-                            gatheredData[field] = structuredData[field];
+                            collectedData[field] = structuredData[field];
                         }
                     }
-                    // Merge gathered data into session
-                    if (Object.keys(gatheredData).length > 0) {
-                        session = await this.updateExtracted(session, gatheredData);
-                        logger.debug(`[Agent] Extracted data:`, gatheredData);
+                    // Merge collected data into session
+                    if (Object.keys(collectedData).length > 0) {
+                        session = await this.updateData(session, collectedData);
+                        logger.debug(`[Agent] Collected data:`, collectedData);
                     }
                 }
                 // Extract any additional data from structured response on final chunk
@@ -382,13 +382,13 @@ export class Agent {
                     await this.updateContext(chunk.structured
                         .contextUpdate);
                 }
-                // Auto-save session state on final chunk
+                // 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 state to persistence: ${session.id}`);
+                    await this.persistenceManager.saveSessionStep(session.id, session);
+                    logger.debug(`[Agent] Auto-saved session step to persistence: ${session.id}`);
                 }
                 // Update current session if we have one
                 if (chunk.done && this.currentSession) {
@@ -407,14 +407,16 @@ export class Agent {
         else if (isRouteComplete && selectedRoute) {
             // Route is complete - generate completion message then check for onComplete transition
             const lastUserMessage = getLastMessageFromHistory(history);
-            // Get endState spec from route
-            const endStateSpec = selectedRoute.endStateSpec;
-            // Create a temporary state for completion message generation using endState configuration
-            const completionState = new State(selectedRoute.id, endStateSpec.chatState || "Summarize what was accomplished and confirm completion", endStateSpec.id || END_STATE_ID, endStateSpec.gather, undefined, endStateSpec.requiredData, endStateSpec.chatState || "Summarize what was accomplished and confirm completion based on the conversation history and collected data");
+            // 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, endStepSpec.instructions ||
+                "Summarize what was accomplished and confirm completion", endStepSpec.id || END_ROUTE_ID, endStepSpec.collect, undefined, endStepSpec.requires, endStepSpec.instructions ||
+                "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, completionState);
+            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, completionStep);
             // Build completion response prompt
-            const completionPrompt = this.responseEngine.buildResponsePrompt(selectedRoute, completionState, selectedRoute.getRules(), selectedRoute.getProhibitions(), undefined, // No directives for completion
+            const completionPrompt = this.responseEngine.buildResponsePrompt(selectedRoute, completionStep, selectedRoute.getRules(), selectedRoute.getProhibitions(), undefined, // No directives for completion
             history, lastUserMessage, {
                 name: this.options.name,
                 goal: this.options.goal,
@@ -434,11 +436,11 @@ export class Agent {
             });
             logger.debug(`[Agent] Streaming completion message for route: ${selectedRoute.title}`);
             // Check for onComplete transition
-            const transitionConfig = await selectedRoute.evaluateOnComplete({ extracted: session.extracted }, effectiveContext);
+            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.transitionTo ||
-                    r.title === transitionConfig.transitionTo);
+                const targetRoute = this.routes.find((r) => r.id === transitionConfig.nextStep ||
+                    r.title === transitionConfig.nextStep);
                 if (targetRoute) {
                     // Set pending transition in session
                     session = {
@@ -452,12 +454,12 @@ export class Agent {
                     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.transitionTo}`);
+                    logger.warn(`[Agent] Route ${selectedRoute.title} completed but target route not found: ${transitionConfig.nextStep}`);
                 }
             }
-            // Set state to END_STATE marker
-            session = enterState(session, END_STATE_ID, "Route completed");
-            logger.debug(`[Agent] Route ${selectedRoute.title} completed. Entered END_STATE state.`);
+            // 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
@@ -541,37 +543,37 @@ export class Agent {
         };
         // Initialize or get session (use current session if available)
         let session = params.session || this.currentSession || createSession();
-        // PHASE 1: TOOL EXECUTION - Execute tools if current state has toolState
-        if (session.currentRoute && session.currentState) {
+        // PHASE 1: TOOL EXECUTION - Execute tools if current step has tool
+        if (session.currentRoute && session.currentStep) {
             const currentRoute = this.routes.find((r) => r.id === session.currentRoute?.id);
             if (currentRoute) {
-                const currentState = currentRoute.getState(session.currentState.id);
-                if (currentState) {
-                    const transitions = currentState.getTransitions();
-                    const toolTransition = transitions.find((t) => t.spec.toolState);
-                    if (toolTransition?.spec.toolState) {
+                const currentStep = currentRoute.getStep(session.currentStep.id);
+                if (currentStep) {
+                    const transitions = currentStep.getTransitions();
+                    const toolTransition = transitions.find((t) => t.spec.tool);
+                    if (toolTransition?.spec.tool) {
                         const toolExecutor = new ToolExecutor();
                         // Get allowed domains from current route for security enforcement
                         const allowedDomains = currentRoute.getDomains();
-                        const result = await toolExecutor.executeTool(toolTransition.spec.toolState, effectiveContext, this.updateContext.bind(this), history, session.extracted, allowedDomains);
+                        const result = await toolExecutor.executeTool(toolTransition.spec.tool, effectiveContext, this.updateContext.bind(this), history, session.data, allowedDomains);
                         // Update context with tool results
                         if (result.contextUpdate) {
                             await this.updateContext(result.contextUpdate);
                         }
-                        // Update extracted data with tool results
-                        if (result.extractedUpdate) {
-                            session = await this.updateExtracted(session, result.extractedUpdate);
-                            logger.debug(`[Agent] Tool updated extracted data:`, result.extractedUpdate);
+                        // Update collected data with tool results
+                        if (result.collectedUpdate) {
+                            session = await this.updateData(session, result.collectedUpdate);
+                            logger.debug(`[Agent] Tool updated collected data:`, result.collectedUpdate);
                         }
                         logger.debug(`[Agent] Executed tool: ${result.toolName} (success: ${result.success})`);
                     }
                 }
             }
         }
-        // PHASE 2: ROUTING + STATE SELECTION - Determine which route and state to use (combined)
+        // PHASE 2: ROUTING + STEP SELECTION - Determine which route and step to use (combined)
         let selectedRoute;
         let responseDirectives;
-        let selectedState;
+        let selectedStep;
         let isRouteComplete = false;
         // Check for pending transition from previous route completion
         if (session.pendingTransition) {
@@ -586,7 +588,7 @@ export class Agent {
                 session = enterRoute(session, targetRoute.id, targetRoute.title);
                 // Merge initial data if available
                 if (targetRoute.initialData) {
-                    session = mergeExtracted(session, targetRoute.initialData);
+                    session = mergeCollected(session, targetRoute.initialData);
                 }
                 selectedRoute = targetRoute;
             }
@@ -601,7 +603,7 @@ export class Agent {
         }
         // If no pending transition or transition handled, do normal routing
         if (this.routes.length > 0 && !selectedRoute) {
-            const orchestration = await this.routingEngine.decideRouteAndState({
+            const orchestration = await this.routingEngine.decideRouteAndStep({
                 routes: this.routes,
                 session,
                 history,
@@ -616,47 +618,47 @@ export class Agent {
                 signal,
             });
             selectedRoute = orchestration.selectedRoute;
-            selectedState = orchestration.selectedState;
+            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_STATE reached`);
+                logger.debug(`[Agent] Route complete: all required data collected, END_ROUTE reached`);
             }
         }
-        // PHASE 3: DETERMINE NEXT STATE - Use state from combined decision or get initial state
+        // PHASE 3: DETERMINE NEXT STEP - Use step from combined decision or get initial step
         let message;
         const toolCalls = undefined;
         if (selectedRoute && !isRouteComplete) {
-            let nextState;
-            // If we have a selected state from the combined routing decision, use it
-            if (selectedState) {
-                nextState = selectedState;
+            let nextStep;
+            // If we have a selected step from the combined routing decision, use it
+            if (selectedStep) {
+                nextStep = selectedStep;
             }
             else {
-                // New route or no state selected - get initial state or first valid state
-                const candidates = this.routingEngine.getCandidateStates(selectedRoute, undefined, session.extracted || {});
+                // 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) {
-                    nextState = candidates[0].state;
-                    logger.debug(`[Agent] Using first valid state: ${nextState.id} for new route`);
+                    nextStep = candidates[0].step;
+                    logger.debug(`[Agent] Using first valid step: ${nextStep.id} for new route`);
                 }
                 else {
-                    // Fallback to initial state even if it should be skipped
-                    nextState = selectedRoute.initialState;
-                    logger.warn(`[Agent] No valid states found, using initial state: ${nextState.id}`);
+                    // 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 state
-            session = enterState(session, nextState.id, nextState.description);
-            logger.debug(`[Agent] Entered state: ${nextState.id}`);
-            // PHASE 4: RESPONSE GENERATION - Generate message using selected route and state
+            // 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 gather fields from state)
-            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, nextState);
+            // Build response schema for this route (with collect fields from step)
+            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, nextStep);
             // Build response prompt
-            const responsePrompt = this.responseEngine.buildResponsePrompt(selectedRoute, nextState, selectedRoute.getRules(), selectedRoute.getProhibitions(), responseDirectives, history, lastUserMessage, {
+            const responsePrompt = this.responseEngine.buildResponsePrompt(selectedRoute, nextStep, selectedRoute.getRules(), selectedRoute.getProhibitions(), responseDirectives, history, lastUserMessage, {
                 name: this.options.name,
                 goal: this.options.goal,
                 description: this.options.description,
@@ -674,20 +676,20 @@ export class Agent {
                 },
             });
             message = result.structured?.message || result.message;
-            // Extract gathered data from response
-            if (result.structured && nextState.gatherFields) {
-                const gatheredData = {};
-                // The structured response includes both base fields and gathered extraction fields
+            // Extract collected data from response
+            if (result.structured && nextStep.collectFields) {
+                const collectedData = {};
+                // The structured response includes both base fields and collected extraction fields
                 const structuredData = result.structured;
-                for (const field of nextState.gatherFields) {
+                for (const field of nextStep.collectFields) {
                     if (field in structuredData) {
-                        gatheredData[field] = structuredData[field];
+                        collectedData[field] = structuredData[field];
                     }
                 }
-                // Merge gathered data into session
-                if (Object.keys(gatheredData).length > 0) {
-                    session = await this.updateExtracted(session, gatheredData);
-                    logger.debug(`[Agent] Extracted data:`, gatheredData);
+                // Merge collected data into session
+                if (Object.keys(collectedData).length > 0) {
+                    session = await this.updateData(session, collectedData);
+                    logger.debug(`[Agent] Collected data:`, collectedData);
                 }
             }
             // Extract any additional data from structured response
@@ -701,14 +703,16 @@ export class Agent {
         else if (isRouteComplete && selectedRoute) {
             // Route is complete - generate completion message then check for onComplete transition
             const lastUserMessage = getLastMessageFromHistory(history);
-            // Get endState spec from route
-            const endStateSpec = selectedRoute.endStateSpec;
-            // Create a temporary state for completion message generation using endState configuration
-            const completionState = new State(selectedRoute.id, endStateSpec.chatState || "Summarize what was accomplished and confirm completion", endStateSpec.id || END_STATE_ID, endStateSpec.gather, undefined, endStateSpec.requiredData, endStateSpec.chatState || "Summarize what was accomplished and confirm completion based on the conversation history and collected data");
+            // 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, endStepSpec.instructions ||
+                "Summarize what was accomplished and confirm completion", endStepSpec.id || END_ROUTE_ID, endStepSpec.collect, undefined, endStepSpec.requires, endStepSpec.instructions ||
+                "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, completionState);
+            const responseSchema = this.responseEngine.responseSchemaForRoute(selectedRoute, completionStep);
             // Build completion response prompt
-            const completionPrompt = this.responseEngine.buildResponsePrompt(selectedRoute, completionState, selectedRoute.getRules(), selectedRoute.getProhibitions(), undefined, // No directives for completion
+            const completionPrompt = this.responseEngine.buildResponsePrompt(selectedRoute, completionStep, selectedRoute.getRules(), selectedRoute.getProhibitions(), undefined, // No directives for completion
             history, lastUserMessage, {
                 name: this.options.name,
                 goal: this.options.goal,
@@ -726,14 +730,15 @@ export class Agent {
                     schemaName: "completion_message",
                 },
             });
-            message = completionResult.structured?.message || completionResult.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({ extracted: session.extracted }, effectiveContext);
+            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.transitionTo ||
-                    r.title === transitionConfig.transitionTo);
+                const targetRoute = this.routes.find((r) => r.id === transitionConfig.nextStep ||
+                    r.title === transitionConfig.nextStep);
                 if (targetRoute) {
                     // Set pending transition in session
                     session = {
@@ -747,12 +752,12 @@ export class Agent {
                     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.transitionTo}`);
+                    logger.warn(`[Agent] Route ${selectedRoute.title} completed but target route not found: ${transitionConfig.nextStep}`);
                 }
             }
-            // Set state to END_STATE marker
-            session = enterState(session, END_STATE_ID, "Route completed");
-            logger.debug(`[Agent] Route ${selectedRoute.title} completed. Entered END_STATE state.`);
+            // 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
@@ -787,12 +792,12 @@ export class Agent {
             });
             message = result.structured?.message || result.message;
         }
-        // Auto-save session state to persistence if configured
+        // 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 state to persistence: ${session.id}`);
+            await this.persistenceManager.saveSessionStep(session.id, session);
+            logger.debug(`[Agent] Auto-saved session step to persistence: ${session.id}`);
         }
         // Update current session if we have one
         if (this.currentSession) {
@@ -800,9 +805,9 @@ export class Agent {
         }
         return {
             message,
-            session, // Return updated session with route/state info
+            session, // Return updated session with route/step info
             toolCalls,
-            isRouteComplete, // Indicates if the route has reached END_STATE with all data collected
+            isRouteComplete, // Indicates if the route has reached END_ROUTE with all data collected
         };
     }
     /**
@@ -877,7 +882,7 @@ export class Agent {
     }
     /**
      * Set the current session for convenience methods
-     * @param session - Session state to use for subsequent calls
+     * @param session - Session step to use for subsequent calls
      */
     setCurrentSession(session) {
         this.currentSession = session;
@@ -895,37 +900,38 @@ export class Agent {
         this.currentSession = undefined;
     }
     /**
-     * Get extracted data from current session
+     * Get collected data from current session
      * @param routeId - Optional route ID to get data for (uses current route if not provided)
-     * @returns The extracted data from the current session
+     * @returns The collected data from the current session
      */
-    getExtractedData(routeId) {
+    getData(routeId) {
         if (!this.currentSession) {
             return {};
         }
         if (routeId) {
-            return (this.currentSession.extractedByRoute?.[routeId] || {});
+            return (this.currentSession.dataByRoute?.[routeId] ||
+                {});
         }
-        return this.currentSession.extracted || {};
+        return this.currentSession.data || {};
     }
     /**
      * 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 state to update (uses current session if not provided)
+     * @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.transitionToRoute("feedback-collection", 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 });
      * }
      */
-    transitionToRoute(routeIdOrTitle, session, condition) {
+    nextStepRoute(routeIdOrTitle, session, condition) {
         const targetSession = session || this.currentSession;
         if (!targetSession) {
             throw new Error("No session provided and no current session available. Please provide a session to transition.");
@@ -933,7 +939,9 @@ export class Agent {
         // 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(", ")}`);
+            throw new Error(`Route not found: ${routeIdOrTitle}. Available routes: ${this.routes
+                .map((r) => r.title)
+                .join(", ")}`);
         }
         const updatedSession = {
             ...targetSession,