gpt-driver-node 1.0.2 → 1.0.4

package/dist/index.mjs

@@ -1,8 +1,10 @@
 import { promises } from 'node:fs';
 import path from 'node:path';
+import { readFile } from 'node:fs/promises';
 import axios from 'axios';
 import sharp from 'sharp';
 import { attach } from 'webdriverio';
+import dotenv from 'dotenv';
 import winston from 'winston';
 import { z } from 'zod';
 import crypto from 'node:crypto';
@@ -20,6 +22,15 @@ function buildUrl(base, extraPath) {
   }
   return `${baseUrl}${extraPath}`;
 }
+const getImageDimensions = async (base64) => {
+  const base64Data = base64.replace(/^data:image\/\w+;base64,/, "");
+  const buffer = Buffer.from(base64Data, "base64");
+  const metadata = await sharp(buffer).metadata();
+  if (!metadata.width || !metadata.height) {
+    throw new Error("Unable to get image dimensions");
+  }
+  return { width: metadata.width, height: metadata.height };
+};
 
 const colors = {
   reset: "\x1B[0m",
@@ -82,6 +93,75 @@ ${logStyles.gray(stack)}` : logMessage;
   ]
 });
 
+const waitForStableScreen = async (getScreenshot, options = {}) => {
+  const {
+    maxTimeoutSec = 5,
+    intervalSec = 0.01,
+    tolerance = 1e-5,
+    pixelThreshold = 0,
+    downscaleWidth = 600,
+    downscaleHeight = 600
+  } = options;
+  const startTime = Date.now();
+  const maxTimeoutMillis = maxTimeoutSec * 1e3;
+  const intervalMillis = intervalSec * 1e3;
+  let previousDownsampledBuffer = null;
+  let lastScreenshotBase64 = null;
+  while (Date.now() - startTime < maxTimeoutMillis) {
+    try {
+      const screenshotBase64 = await getScreenshot();
+      lastScreenshotBase64 = screenshotBase64;
+      const imageBuffer = Buffer.from(screenshotBase64, "base64");
+      const downsampledBuffer = await sharp(imageBuffer).resize(downscaleWidth, downscaleHeight, { fit: "fill" }).ensureAlpha().raw().toBuffer();
+      if (previousDownsampledBuffer) {
+        const isSimilar = areImagesSimilar(
+          previousDownsampledBuffer,
+          downsampledBuffer,
+          downscaleWidth,
+          downscaleHeight,
+          tolerance,
+          pixelThreshold
+        );
+        if (isSimilar) {
+          return {
+            stable: true,
+            originalScreenshotBase64: screenshotBase64
+          };
+        }
+      }
+      previousDownsampledBuffer = downsampledBuffer;
+    } catch (e) {
+      globalLogger.warn(`Error during stability check: ${e}`);
+      throw e;
+    }
+    await delay(intervalMillis);
+  }
+  return {
+    stable: false,
+    originalScreenshotBase64: lastScreenshotBase64
+  };
+};
+function areImagesSimilar(buffer1, buffer2, width, height, tolerance, pixelThreshold) {
+  if (buffer1.length !== buffer2.length) {
+    return false;
+  }
+  const totalPixels = width * height;
+  let differentPixels = 0;
+  for (let i = 0; i < buffer1.length; i += 4) {
+    const r1 = buffer1[i];
+    const g1 = buffer1[i + 1];
+    const b1 = buffer1[i + 2];
+    const r2 = buffer2[i];
+    const g2 = buffer2[i + 1];
+    const b2 = buffer2[i + 2];
+    if (Math.abs(r1 - r2) > pixelThreshold || Math.abs(g1 - g2) > pixelThreshold || Math.abs(b1 - b2) > pixelThreshold) {
+      differentPixels++;
+    }
+  }
+  const diffRatio = differentPixels / totalPixels;
+  return diffRatio <= tolerance;
+}
+
 const SavableStepBaseSchema = z.object({
   id: z.number().optional(),
   descriptionText: z.string().optional(),
@@ -105,9 +185,17 @@ const SavableTypeStepSchema = SavableStepBaseSchema.extend({
   type: z.literal("type"),
   text: z.string()
 });
-const SavableScrollStepSchema = SavableStepBaseSchema.extend({
-  type: z.literal("scroll"),
-  direction: z.enum(["up", "down"])
+const SavableSwipeStepSchema = SavableStepBaseSchema.extend({
+  type: z.literal("swipe"),
+  direction: z.enum(["left", "right", "up", "down"]),
+  x1: z.number().optional(),
+  y1: z.number().optional(),
+  x2: z.number().optional(),
+  y2: z.number().optional(),
+  duration: z.number().optional().default(500)
+});
+const SavableScrollStepSchema = SavableSwipeStepSchema.extend({
+  type: z.literal("scroll")
 });
 const SavableZoomStepSchema = SavableStepBaseSchema.extend({
   type: z.literal("zoom"),
@@ -128,6 +216,10 @@ const SavableAIStepSchema = SavableStepBaseSchema.extend({
   type: z.literal("ai"),
   instruction: z.string()
 });
+const SavableEnterStepSchema = SavableStepBaseSchema.extend({
+  type: z.literal("enter"),
+  delayNextStep: z.number().optional().default(500)
+});
 const SavableFileRefStepSchema = SavableStepBaseSchema.extend({
   type: z.literal("fileRef"),
   path: z.string(),
@@ -140,6 +232,8 @@ const SavableStepSchema = z.discriminatedUnion("type", [
   // type: 'assert'
   SavableTypeStepSchema,
   // type: 'type'
+  SavableSwipeStepSchema,
+  // type: 'swipe'
   SavableScrollStepSchema,
   // type: 'scroll'
   SavableZoomStepSchema,
@@ -150,6 +244,8 @@ const SavableStepSchema = z.discriminatedUnion("type", [
   // type: 'deeplink'
   SavableAIStepSchema,
   // type: 'ai'
+  SavableEnterStepSchema,
+  // type: 'enter'
   SavableFileRefStepSchema
   // type: 'fileRef'
 ]);
@@ -171,7 +267,7 @@ const CACHE_SERVER_URL = "https://cache.mobileboost.io";
 const GPT_DRIVER_BASE_URL = "https://api.mobileboost.io";
 const RESCALE_FACTOR = 4;
 const SMART_LOOP_MAX_ITERATIONS = 15;
-const CACHE_RETRY_MS = 2e3;
+const CACHE_RETRY_MS = 1500;
 const CACHE_CHECK_INTERVAL_MS = 500;
 
 function generateCacheHash(apiKey, filepath, stepNumber, description, platform, resolution) {
@@ -255,15 +351,24 @@ async function executeFromCache(params) {
     return { found: false };
   } catch (error) {
     if (axios.isAxiosError(error)) {
-      globalLogger.warn(`[Cache] Cache lookup failed: ${error.response?.data || error.message}`);
+      const errorMsg = `Cache lookup failed: ${error.response?.data || error.message}`;
+      globalLogger.warn(`[Cache] ${errorMsg}`);
     } else {
-      globalLogger.error(`[Cache] Error executing from cache: ${error}`);
+      const errorMsg = `Error executing from cache: ${error}`;
+      globalLogger.error(`[Cache] ${errorMsg}`);
     }
     return { found: false };
   }
 }
 async function populateCache(params) {
   try {
+    globalLogger.debug(`[populateCache] Parameters: ${JSON.stringify({
+      stepNumber: params.stepNumber,
+      filepath: params.filepath,
+      platform: params.platform,
+      screenResolution: params.screenResolution,
+      executionDataCount: params.executionData.length
+    })}`);
     const hash = generateCacheHash(
       params.apiKey,
       params.filepath,
@@ -272,13 +377,15 @@ async function populateCache(params) {
       params.platform,
       params.screenResolution
     );
+    globalLogger.debug(`[populateCache] Generated hash: ${hash}`);
     const payload = await Promise.all(params.executionData.map(async (item) => {
       const resizedBuffer = await resizeScreenshotForCache(item.screenshot);
+      const scaledScreenshotBase64 = resizedBuffer.toString("base64");
       const scaledCommands = item.commands.map(
         (cmd) => scaleCommand(cmd, "divide")
       );
       return {
-        screenshot: resizedBuffer.toString("base64"),
+        screenshot: scaledScreenshotBase64,
         commands: scaledCommands
       };
     }));
@@ -290,9 +397,11 @@ async function populateCache(params) {
     return { success: true };
   } catch (error) {
     if (axios.isAxiosError(error)) {
-      globalLogger.error(`[Cache] Failed to populate cache: ${error.response?.data || error.message}`);
+      const errorMsg = `Failed to populate cache: ${error.response?.data || error.message}`;
+      globalLogger.error(`[Cache] ${errorMsg}`);
     } else {
-      globalLogger.error(`[Cache] Error populating cache: ${error}`);
+      const errorMsg = `Error populating cache: ${error}`;
+      globalLogger.error(`[Cache] ${errorMsg}`);
     }
     return { success: false };
   }
@@ -422,9 +531,37 @@ function isWaitCommand(cmd) {
 function isScrollCommand(cmd) {
   return cmd.startsWith("scroll:");
 }
+function isEnterCommand(cmd) {
+  const key = cmd.toLowerCase().split("press:")[1]?.trim() ?? "";
+  return key === "enter";
+}
 function isTypeCommand(cmd) {
   return cmd.startsWith("type:");
 }
+function isSlideCommand(cmd) {
+  return cmd.startsWith("slide");
+}
+function parseSlideCommand(cmd) {
+  const slideMatch = cmd.match(
+    /slide\s+(up|down|left|right)\s+(\d+)%(?::\s*[^;]*)?;(\d+);(\d+)/i
+  );
+  if (!slideMatch) {
+    return null;
+  }
+  const extractedDirection = slideMatch[1].toLowerCase();
+  const directionMap = {
+    down: "up",
+    up: "down",
+    left: "left",
+    right: "right"
+  };
+  return {
+    direction: directionMap[extractedDirection],
+    percentage: parseInt(slideMatch[2], 10),
+    startX: parseInt(slideMatch[3], 10),
+    startY: parseInt(slideMatch[4], 10)
+  };
+}
 
 async function executeSmartLoop(ctx, params) {
   const maxCacheAttempts = Math.floor(CACHE_RETRY_MS / CACHE_CHECK_INTERVAL_MS);
@@ -433,35 +570,56 @@ async function executeSmartLoop(ctx, params) {
   let lastCacheIndex = void 0;
   let anyCacheMiss = false;
   let everHadCacheHit = false;
+  let totalCacheHits = 0;
   const currentExecutionData = [];
+  const stepStartTime = performance.now();
+  const iterationTimes = [];
   globalLogger.info(`[SmartLoop] Starting for step ${params.stepNumber}: "${params.description}"`);
+  globalLogger.debug(`[Performance][SmartLoop] Step execution started at ${stepStartTime.toFixed(2)}ms`);
   try {
     while (loopCount < SMART_LOOP_MAX_ITERATIONS) {
+      const iterationStartTime = performance.now();
+      globalLogger.debug(`[SmartLoop] Starting iteration ${loopCount + 1}/${SMART_LOOP_MAX_ITERATIONS}`);
       let screenshot = "";
       let commands = [];
       let isCacheHit = false;
+      let screenshotResolution = void 0;
+      const stabilityResult = await waitForStableScreen(ctx.getScreenshot);
       for (let attempt = 0; attempt < maxCacheAttempts; attempt++) {
-        screenshot = await ctx.getScreenshot();
+        const screenshotStartTime = performance.now();
+        const screenshotEndTime = performance.now();
+        globalLogger.debug(`[Performance][SmartLoop] Screenshot capture took ${(screenshotEndTime - screenshotStartTime).toFixed(2)}ms`);
+        if (!stabilityResult.stable) {
+          globalLogger.warn("[SmartLoop] Screen did not stabilize within timeout, proceeding with last screenshot");
+        }
+        screenshot = stabilityResult.originalScreenshotBase64;
+        if (screenshotResolution === void 0) {
+          screenshotResolution = await getImageDimensions(screenshot);
+        }
         const sizeInBytes = screenshot.length * 0.75;
         const sizeInMB = (sizeInBytes / (1024 * 1024)).toFixed(2);
         globalLogger.debug(`[SmartLoop] Captured screenshot: ~${sizeInMB} MB`);
         try {
           globalLogger.debug(`[SmartLoop] Checking cache (Attempt ${attempt + 1}/${maxCacheAttempts})`);
+          const cacheCheckStartTime = performance.now();
           const cacheResult = await executeFromCache({
             apiKey: ctx.organisationId,
             stepNumber: params.stepNumber,
             stepDescription: params.description,
             screenshot,
-            screenResolution: ctx.screenSize,
+            screenResolution: screenshotResolution,
             highestUsedIndex: lastCacheIndex,
             platform: ctx.platform,
             filepath: params.filepath
           });
+          const cacheCheckEndTime = performance.now();
+          globalLogger.debug(`[Performance][SmartLoop] Cache check took ${(cacheCheckEndTime - cacheCheckStartTime).toFixed(2)}ms`);
           if (cacheResult.found && cacheResult.cacheCommands) {
             commands = cacheResult.cacheCommands;
             lastCacheIndex = cacheResult.cacheIndex;
             isCacheHit = true;
             everHadCacheHit = true;
+            totalCacheHits++;
             globalLogger.info(`[SmartLoop] Cache Hit! (${commands.length} commands)`);
             break;
           }
@@ -473,18 +631,53 @@ async function executeSmartLoop(ctx, params) {
           await delay(CACHE_CHECK_INTERVAL_MS);
         }
       }
+      if (screenshotResolution === void 0) {
+        const screenshot2 = await ctx.getScreenshot();
+        screenshotResolution = await getImageDimensions(screenshot2);
+      }
       let aiCommands = [];
+      let actionDescription = [];
       if (!isCacheHit) {
         anyCacheMiss = true;
         globalLogger.info(`[SmartLoop] Cache Miss. Requesting AI agent...`);
-        const agentResponse = await executeAgentStep({
-          apiKey: ctx.organisationId,
-          base64_screenshot: screenshot,
-          instruction: params.instruction,
-          action_history: actionHistory
-        });
-        aiCommands = agentResponse.appetizeCommands || [];
-        const gptCommands = agentResponse.gptCommands || [];
+        const aiStartTime = performance.now();
+        let agentResponse;
+        if (ctx.middleLayerAssertFn) {
+          const response = await ctx.middleLayerAssertFn(screenshot);
+          const results = response.data.results;
+          const failedConditions = Object.entries(results).filter(([_, success]) => !success).map(([key, _]) => key);
+          if (failedConditions.length === 0) {
+            agentResponse = {
+              appetizeCommands: [
+                "task complete: All assertions passed"
+              ]
+            };
+          } else {
+            agentResponse = {
+              appetizeCommands: [
+                `error detected: Failed conditions: ${failedConditions.join(", ")}`
+              ]
+            };
+          }
+        } else {
+          agentResponse = await executeAgentStep({
+            apiKey: ctx.organisationId,
+            base64_screenshot: screenshot,
+            instruction: params.instruction,
+            action_history: actionHistory
+          });
+        }
+        const aiEndTime = performance.now();
+        globalLogger.debug(`[Performance][SmartLoop] AI agent call took ${(aiEndTime - aiStartTime).toFixed(2)}ms`);
+        aiCommands = agentResponse.appetizeCommands ?? [];
+        const gptCommands = agentResponse.gptCommands ?? [];
+        actionDescription = [];
+        const actionDescriptionIndex = gptCommands.findIndex(
+          (entry) => entry.startsWith("actions_description:")
+        );
+        if (actionDescriptionIndex !== -1) {
+          actionDescription = gptCommands.slice(actionDescriptionIndex, actionDescriptionIndex + 1);
+        }
         const reasoningIndex = gptCommands.findIndex((entry) => entry.startsWith("reasoning:"));
         if (reasoningIndex !== -1) {
           const parsedCommands = gptCommands.slice(reasoningIndex);
@@ -494,19 +687,23 @@ async function executeSmartLoop(ctx, params) {
           }
           actionHistory = [...actionHistory, ...parsedCommands];
         }
-        commands = [...aiCommands];
+        commands = [...actionDescription, ...aiCommands];
         globalLogger.debug(`[SmartLoop] AI returned ${commands.length} command(s)`);
       }
       currentExecutionData.push({
         screenshot,
-        commands: aiCommands.length > 0 ? aiCommands : commands
+        commands
       });
-      await ctx.logCodeExecution(screenshot, commands.join("\n"));
+      const logPromise = ctx.logCodeExecution(screenshot, commands.join("\n"), isCacheHit);
+      if (ctx.pendingLogPromises) {
+        ctx.pendingLogPromises.push(logPromise);
+      }
       let actionExecuted = false;
       let taskCompleted = false;
       if (commands.length > 0) {
         globalLogger.debug(`[SmartLoop] Executing ${commands.length} command(s)`);
       }
+      const commandExecutionStartTime = performance.now();
       for (const cmd of commands) {
         if (isTaskComplete(cmd)) {
           taskCompleted = true;
@@ -523,9 +720,18 @@ async function executeSmartLoop(ctx, params) {
           const coords = parseTapCoordinates(cmd);
           if (coords) {
             globalLogger.debug(`[SmartLoop] Executing tap at (${coords.x}, ${coords.y})`);
-            await ctx.performTap(coords.x, coords.y);
+            await ctx.performTap(
+              coords.x,
+              coords.y,
+              screenshotResolution.width,
+              screenshotResolution.height
+            );
             actionExecuted = true;
           }
+        } else if (isEnterCommand(cmd)) {
+          globalLogger.debug(`[SmartLoop] Pressing Enter`);
+          await ctx.performPressEnter();
+          actionExecuted = true;
         } else if (isWaitCommand(cmd)) {
           const seconds = parseWaitSeconds(cmd);
           if (seconds) {
@@ -537,7 +743,50 @@ async function executeSmartLoop(ctx, params) {
           const direction = parseScrollDirection(cmd);
           if (direction) {
             globalLogger.debug(`[SmartLoop] Scrolling ${direction}`);
-            await ctx.performScroll(direction);
+            await ctx.performSwipe({ direction });
+            if (isCacheHit) {
+              await delay(650);
+            }
+            actionExecuted = true;
+          }
+        } else if (isSlideCommand(cmd)) {
+          const slideParams = parseSlideCommand(cmd);
+          if (slideParams) {
+            const { direction, percentage, startX, startY } = slideParams;
+            const isVertical = direction === "up" || direction === "down";
+            const distance = Math.round(
+              (isVertical ? screenshotResolution.height : screenshotResolution.width) * (percentage / 100)
+            );
+            let endX = startX;
+            let endY = startY;
+            switch (direction) {
+              case "up":
+                endY = startY + distance;
+                break;
+              case "down":
+                endY = startY - distance;
+                break;
+              case "left":
+                endX = startX - distance;
+                break;
+              case "right":
+                endX = startX + distance;
+                break;
+            }
+            globalLogger.debug(`[SmartLoop] Sliding ${direction} ${percentage}% from (${startX}, ${startY}) to (${endX}, ${endY})`);
+            await ctx.performSwipe({
+              direction,
+              x1: startX,
+              y1: startY,
+              x2: endX,
+              y2: endY,
+              screenshotWidth: screenshotResolution.width,
+              screenshotHeight: screenshotResolution.height,
+              duration: 500
+            });
+            if (isCacheHit) {
+              await delay(650);
+            }
             actionExecuted = true;
           }
         } else if (isTypeCommand(cmd)) {
@@ -550,49 +799,83 @@ async function executeSmartLoop(ctx, params) {
         }
       }
       if (actionExecuted) {
+        const commandExecutionEndTime = performance.now();
+        globalLogger.debug(`[Performance][SmartLoop] Command execution took ${(commandExecutionEndTime - commandExecutionStartTime).toFixed(2)}ms`);
         if (isCacheHit) {
           actionHistory.push(...commands);
         }
         await delay(100);
       }
+      const iterationEndTime = performance.now();
+      const iterationDuration = iterationEndTime - iterationStartTime;
+      iterationTimes.push(iterationDuration);
+      globalLogger.debug(`[Performance][SmartLoop] Iteration ${loopCount + 1} completed in ${iterationDuration.toFixed(2)}ms (${(iterationDuration / 1e3).toFixed(2)}s)`);
       if (taskCompleted) {
         globalLogger.info(`[SmartLoop] Task completed successfully`);
+        const stepEndTime2 = performance.now();
+        const totalDuration2 = stepEndTime2 - stepStartTime;
+        const totalSeconds2 = totalDuration2 / 1e3;
+        const totalMinutes2 = totalSeconds2 / 60;
+        const averageIterationTime = iterationTimes.reduce((sum, time) => sum + time, 0) / iterationTimes.length;
+        globalLogger.debug(`[Performance][SmartLoop] Step execution summary:`);
+        globalLogger.debug(`[Performance][SmartLoop]   - Total iterations: ${loopCount + 1}`);
+        globalLogger.debug(`[Performance][SmartLoop]   - Total duration: ${totalDuration2.toFixed(2)}ms (${totalSeconds2.toFixed(2)}s / ${totalMinutes2.toFixed(2)}min)`);
+        globalLogger.debug(`[Performance][SmartLoop]   - Average iteration time: ${averageIterationTime.toFixed(2)}ms (${(averageIterationTime / 1e3).toFixed(2)}s)`);
+        globalLogger.debug(`[Performance][SmartLoop]   - Individual iteration times: ${iterationTimes.map((t) => `${t.toFixed(2)}ms`).join(", ")}`);
         if (anyCacheMiss && currentExecutionData.length > 0) {
           globalLogger.info(`[SmartLoop] Populating cache with ${currentExecutionData.length} frame(s)...`);
-          try {
-            await populateCache({
-              apiKey: ctx.organisationId,
-              stepNumber: params.stepNumber,
-              stepDescription: params.description,
-              executionData: currentExecutionData,
-              screenResolution: ctx.screenSize,
-              platform: ctx.platform,
-              filepath: params.filepath
-            });
+          const cachePopulateStartTime = performance.now();
+          populateCache({
+            apiKey: ctx.organisationId,
+            stepNumber: params.stepNumber,
+            stepDescription: params.description,
+            executionData: currentExecutionData,
+            screenResolution: screenshotResolution,
+            platform: ctx.platform,
+            filepath: params.filepath
+          }).then(() => {
+            const cachePopulateEndTime = performance.now();
+            globalLogger.debug(`[Performance][SmartLoop] Cache population took ${(cachePopulateEndTime - cachePopulateStartTime).toFixed(2)}ms`);
             globalLogger.debug(`[SmartLoop] Cache populated successfully`);
-          } catch (e) {
-            globalLogger.warn(`[SmartLoop] Failed to populate cache: ${e.message}`);
-          }
+          }).catch((e) => globalLogger.warn(`[SmartLoop] Cache population failed: ${e.message}`));
         } else if (!anyCacheMiss) {
           globalLogger.debug(`[SmartLoop] Skipping cache population (all actions were cached)`);
         }
         return {
           success: true,
           iterations: loopCount + 1,
-          cacheHit: everHadCacheHit
+          cacheHit: everHadCacheHit,
+          cacheHitCount: totalCacheHits
         };
       }
       loopCount++;
     }
+    const stepEndTime = performance.now();
+    const totalDuration = stepEndTime - stepStartTime;
+    const totalSeconds = totalDuration / 1e3;
+    const totalMinutes = totalSeconds / 60;
+    globalLogger.debug(`[Performance][SmartLoop] Timeout reached after ${loopCount} iterations`);
+    globalLogger.debug(`[Performance][SmartLoop]   - Total duration: ${totalDuration.toFixed(2)}ms (${totalSeconds.toFixed(2)}s / ${totalMinutes.toFixed(2)}min)`);
+    globalLogger.debug(`[Performance][SmartLoop]   - Individual iteration times: ${iterationTimes.map((t) => `${t.toFixed(2)}ms`).join(", ")}`);
     throw new Error(`Smart Loop timeout after ${SMART_LOOP_MAX_ITERATIONS} iterations`);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    const stepEndTime = performance.now();
+    const totalDuration = stepEndTime - stepStartTime;
+    const totalSeconds = totalDuration / 1e3;
+    const totalMinutes = totalSeconds / 60;
     globalLogger.error(`[SmartLoop] Error: ${message}`);
+    globalLogger.debug(`[Performance][SmartLoop] Error occurred after ${loopCount + 1} iteration(s)`);
+    globalLogger.debug(`[Performance][SmartLoop]   - Total duration before error: ${totalDuration.toFixed(2)}ms (${totalSeconds.toFixed(2)}s / ${totalMinutes.toFixed(2)}min)`);
+    if (iterationTimes.length > 0) {
+      globalLogger.debug(`[Performance][SmartLoop]   - Individual iteration times: ${iterationTimes.map((t) => `${t.toFixed(2)}ms`).join(", ")}`);
+    }
     return {
       success: false,
       error: message,
       iterations: loopCount + 1,
-      cacheHit: everHadCacheHit
+      cacheHit: everHadCacheHit,
+      cacheHitCount: totalCacheHits
     };
   }
 }
@@ -623,8 +906,13 @@ class GptDriver {
   step_number = 1;
   organisationId;
   configFilePath;
+  // Session Execution Stats
+  _stats_startTime = 0;
+  _stats_executedSteps = 0;
+  _stats_cacheHits = 0;
   // Smart loop state - maintains action history across steps for context
   globalActionHistory = [];
+  pendingLogPromises = [];
   /**
    * Creates an instance of the GptDriver class.
    *
@@ -697,6 +985,9 @@ class GptDriver {
    */
   async startSession() {
     globalLogger.info("Starting session...");
+    this._stats_startTime = performance.now();
+    this._stats_executedSteps = 0;
+    this._stats_cacheHits = 0;
     if (!this.useGptDriverCloud) {
       if (this.driver) {
         let platform;
@@ -796,6 +1087,37 @@ class GptDriver {
   getSessionLink() {
     return `https://app.mobileboost.io/gpt-driver/sessions/${this.gptDriverSessionId}`;
   }
+  /**
+   * Stops the current GPTDriver session and update its state.
+   *
+   * This method sends a request to the GPT Driver server to stop the session and logs the session status as either "failed" or "success."
+   *
+   * @param {"failed" | "success"} status - Indicates the outcome of the session.
+   *                                         Use "success" if the session completed as expected,
+   *                                         or "failed" if the session encountered an error or issue.
+   *
+   * @throws {Error} If the request to stop the session fails.
+   */
+  /**
+   * Marks the current GPTDriver session as succeeded.
+   *
+   * This method stops the session and logs it as "succeeded"
+   *
+   * @throws {Error} If the request to stop the session fails.
+   */
+  async setSessionSucceeded() {
+    await this.setSessionStatus("succeeded");
+  }
+  /**
+   * Marks the current GPTDriver session as failed.
+   *
+   * This method stops the session and logs it as "failed."
+   *
+   * @throws {Error} If the request to stop the session fails.
+   */
+  async setSessionFailed() {
+    await this.setSessionStatus("failed");
+  }
   /**
    * Stops the current GPTDriver session and update its state.
    *
@@ -808,7 +1130,13 @@ class GptDriver {
    * @throws {Error} If the request to stop the session fails.
    */
   async setSessionStatus(status) {
+    try {
+      await Promise.all(this.pendingLogPromises);
+    } catch (e) {
+      globalLogger.error(`Error waiting for pending log promises: ${e.message}`);
+    }
     if (this.gptDriverSessionId) {
+      this.printSessionSummary();
       globalLogger.info(`Stopping session with status: ${status}`);
       await axios.post(
         `${this.gptDriverBaseUrl}/sessions/${this.gptDriverSessionId}/stop`,
@@ -824,6 +1152,19 @@ class GptDriver {
       this.globalActionHistory = [];
     }
   }
+  printSessionSummary() {
+    if (this._stats_startTime === 0) return;
+    const endTime = performance.now();
+    const totalTime = (endTime - this._stats_startTime) / 1e3;
+    globalLogger.info(`
+${"=".repeat(50)}`);
+    globalLogger.info(`Session Execution Summary:`);
+    globalLogger.info(`Total Session Time: ${totalTime.toFixed(2)} seconds`);
+    globalLogger.info(`Total Steps executed: ${this._stats_executedSteps}`);
+    globalLogger.info(`Total Step Cache Hits: ${this._stats_cacheHits}`);
+    globalLogger.info(`${"=".repeat(50)}
+`);
+  }
   // ─────────────────────────────────────────────────────────────────────────────
   // SMART LOOP INTEGRATION
   // ─────────────────────────────────────────────────────────────────────────────
@@ -831,21 +1172,23 @@ class GptDriver {
    * Creates a SmartLoopContext for the current session.
    * This context provides all the callbacks needed by the smart loop executor.
    */
-  createSmartLoopContext() {
+  createSmartLoopContext(options) {
     if (!this.organisationId) {
       throw new Error("Organisation ID is missing, please set it in the GPTDriver constructor");
     }
     return {
       apiKey: this.apiKey,
       platform: this.appiumSessionConfig?.platform,
-      screenSize: this.appiumSessionConfig.size,
       globalActionHistory: this.globalActionHistory,
-      getScreenshot: () => this.getScreenshot(this.appiumSessionConfig),
-      performTap: (x, y) => this.performTap(x, y),
-      performScroll: (direction) => this.performScroll(direction),
+      getScreenshot: () => this.getScreenshot(this.appiumSessionConfig, false),
+      performTap: (x, y, screenshotWidth, screenshotHeight) => this.performTap(x, y, screenshotWidth, screenshotHeight),
+      performSwipe: (params) => this.performSwipe(params),
       performType: (text) => this.performType(text),
-      logCodeExecution: async (screenshot, command) => this.logCodeExecution(screenshot, command),
-      organisationId: this.organisationId
+      performPressEnter: () => this.performPressEnter(),
+      logCodeExecution: async (screenshot, command, isCacheHit) => this.logCodeExecution(screenshot, command, isCacheHit),
+      organisationId: this.organisationId,
+      middleLayerAssertFn: options?.middleLayerAssertFn,
+      pendingLogPromises: options?.pendingLogPromises
     };
   }
   /**
@@ -895,15 +1238,31 @@ class GptDriver {
   /**
    * Performs a tap action at the specified coordinates.
    */
-  async performTap(x, y) {
+  async performTap(x, y, screenshotWidth, screenshotHeight) {
     const client = await this.getWdioClient();
+    const platform = this.appiumSessionConfig?.platform;
+    const { width: w, height: h } = this.appiumSessionConfig?.size ?? { width: 1080, height: 1920 };
+    const scaled = this.scaleForIOS(
+      x,
+      y,
+      platform,
+      screenshotWidth,
+      screenshotHeight,
+      w,
+      h
+    );
+    const clampedX = this.clamp(scaled.x, 0, w - 1);
+    const clampedY = this.clamp(scaled.y, 0, h - 1);
+    globalLogger.debug(
+      `[Tap] Platform: ${platform}, Input: ${x},${y}, Window: ${w}x${h}, Final: ${clampedX},${clampedY}`
+    );
     await client.performActions([
       {
         type: "pointer",
         id: "finger1",
         parameters: { pointerType: "touch" },
         actions: [
-          { type: "pointerMove", duration: 0, x, y },
+          { type: "pointerMove", duration: 0, x: clampedX, y: clampedY },
           { type: "pointerDown", button: 0 },
           { type: "pause", duration: 100 },
           { type: "pointerUp", button: 0 }
@@ -913,25 +1272,143 @@ class GptDriver {
   }
   async performType(text) {
     const client = await this.getWdioClient();
-    await client.keys(text.split(""));
+    const platform = this.appiumSessionConfig?.platform;
+    if (platform === "iOS") {
+      const actions = text.split("").flatMap((char) => [
+        { type: "keyDown", value: char },
+        { type: "keyUp", value: char }
+      ]);
+      await client.performActions([
+        {
+          type: "key",
+          id: "keyboard",
+          actions
+        }
+      ]);
+    } else {
+      await client.keys(text.split(""));
+    }
+  }
+  async performPressEnter() {
+    const client = await this.getWdioClient();
+    const platform = this.appiumSessionConfig?.platform;
+    if (platform === "iOS") {
+      await client.performActions([
+        {
+          type: "key",
+          id: "keyboard",
+          actions: [
+            { type: "keyDown", value: "\uE007" },
+            { type: "keyUp", value: "\uE007" }
+          ]
+        }
+      ]);
+    } else {
+      await client.keys(["Enter"]);
+    }
+  }
+  clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+  }
+  scaleForIOS(x, y, platform, screenshotWidth, screenshotHeight, windowWidth, windowHeight) {
+    if (platform !== "iOS" || !screenshotWidth || !screenshotHeight || !windowWidth || !windowHeight) {
+      return { x: Math.round(x), y: Math.round(y) };
+    }
+    const scaleX = windowWidth / screenshotWidth;
+    const scaleY = windowHeight / screenshotHeight;
+    return {
+      x: Math.round(x * scaleX),
+      y: Math.round(y * scaleY)
+    };
   }
-  async performScroll(direction) {
+  async performSwipe(params) {
     const client = await this.getWdioClient();
-    const w = this.appiumSessionConfig?.size?.width ?? 1080;
-    const h = this.appiumSessionConfig?.size?.height ?? 1920;
-    const x = Math.round(w / 2);
-    const startY = direction === "down" ? Math.round(h * 0.8) : Math.round(h * 0.2);
-    const endY = direction === "down" ? Math.round(h * 0.2) : Math.round(h * 0.8);
+    const platform = this.appiumSessionConfig?.platform;
+    const { width: w, height: h } = this.appiumSessionConfig?.size ?? { width: 1080, height: 1920 };
+    const defaultStartX = w / 2;
+    let defaultStartY;
+    if (params.direction === "down") {
+      defaultStartY = h * 0.75;
+    } else if (params.direction === "up") {
+      defaultStartY = h * 0.25;
+    } else {
+      defaultStartY = h / 2;
+    }
+    let startX;
+    let startY;
+    if (params.x1 !== void 0 || params.y1 !== void 0) {
+      const scaled = this.scaleForIOS(
+        params.x1 ?? defaultStartX,
+        params.y1 ?? defaultStartY,
+        platform,
+        params.screenshotWidth,
+        params.screenshotHeight,
+        w,
+        h
+      );
+      startX = scaled.x;
+      startY = scaled.y;
+    } else {
+      startX = Math.round(defaultStartX);
+      startY = Math.round(defaultStartY);
+    }
+    startX = this.clamp(startX, 0, w - 1);
+    startY = this.clamp(startY, 0, h - 1);
+    let endX;
+    let endY;
+    if (params.x2 !== void 0 || params.y2 !== void 0) {
+      const scaled = this.scaleForIOS(
+        params.x2 ?? startX,
+        params.y2 ?? startY,
+        platform,
+        params.screenshotWidth,
+        params.screenshotHeight,
+        w,
+        h
+      );
+      endX = scaled.x;
+      endY = scaled.y;
+    } else {
+      const deltaX = Math.round(w * 0.5);
+      const deltaY = Math.round(h * 0.5);
+      switch (params.direction) {
+        case "left":
+          endX = Math.max(0, startX - deltaX);
+          endY = startY;
+          break;
+        case "right":
+          endX = Math.min(w - 1, startX + deltaX);
+          endY = startY;
+          break;
+        case "up":
+          endX = startX;
+          endY = Math.min(h - 1, startY + deltaY);
+          break;
+        case "down":
+          endX = startX;
+          endY = Math.max(0, startY - deltaY);
+          break;
+        default:
+          endX = startX;
+          endY = startY;
+      }
+    }
+    endX = this.clamp(endX, 0, w - 1);
+    endY = this.clamp(endY, 0, h - 1);
+    globalLogger.debug(
+      `[Swipe] Platform: ${platform}, Direction: ${params.direction}, Start: ${startX},${startY}, End: ${endX},${endY}`
+    );
+    const duration = params.duration ?? 500;
     await client.performActions([
       {
         type: "pointer",
         id: "finger1",
         parameters: { pointerType: "touch" },
         actions: [
-          { type: "pointerMove", duration: 0, x, y: startY },
+          { type: "pointerMove", duration: 0, x: startX, y: startY },
           { type: "pointerDown", button: 0 },
           { type: "pause", duration: 100 },
-          { type: "pointerMove", duration: 500, x, y: endY },
+          { type: "pointerMove", duration, x: endX, y: endY },
           { type: "pointerUp", button: 0 }
         ]
       }
@@ -950,17 +1427,17 @@ class GptDriver {
       if (found) {
         return;
       }
-      await this.performScroll(direction);
+      await this.performSwipe({ direction });
       await this._delay(500);
     }
     throw new Error(`scrollUntil target not found after ${max} scroll(s)`);
   }
-  async getScreenshot(appiumSessionConfig) {
+  async getScreenshot(appiumSessionConfig, shouldScale = true) {
     globalLogger.debug("Capturing screenshot...");
     const url = buildUrl(this.appiumSessionConfig.serverUrl, `/session/${this.appiumSessionConfig.id}/screenshot`);
     const screenshotResponse = await axios.get(url);
     let screenshot = await screenshotResponse.data.value;
-    if (appiumSessionConfig.platform === "iOS") {
+    if (appiumSessionConfig.platform === "iOS" && shouldScale) {
       globalLogger.debug(`Resizing iOS screenshot to ${appiumSessionConfig.size.width}x${appiumSessionConfig.size.height}`);
       const imageBuffer = Buffer.from(screenshot, "base64");
       const transformedImage = await sharp(imageBuffer).resize(appiumSessionConfig.size.width, appiumSessionConfig.size.height).toBuffer();
@@ -1014,41 +1491,71 @@ class GptDriver {
     }
   }
   async aiExecute(commandOrOptions, options) {
+    const startTime = performance.now();
+    globalLogger.debug(`[Performance] aiExecute started at ${startTime.toFixed(2)}ms`);
     const command = typeof commandOrOptions === "string" ? commandOrOptions : commandOrOptions.command;
     const opts = typeof commandOrOptions === "string" ? options : commandOrOptions;
     const appiumHandler = opts?.appiumHandler;
     const cachingMode = opts?.cachingMode;
     const useSmartLoop = opts?.useSmartLoop ?? false;
     if (!this.appiumSessionStarted) {
+      const sessionStartTime = performance.now();
+      globalLogger.debug(`[Performance] Starting session...`);
       await this.startSession();
+      const sessionEndTime = performance.now();
+      globalLogger.debug(`[Performance] Session started in ${(sessionEndTime - sessionStartTime).toFixed(2)}ms`);
     }
     globalLogger.info(`Executing command: ${command}`);
     const driver = this.driver;
     if (appiumHandler != null) {
       try {
+        const handlerStartTime = performance.now();
+        globalLogger.debug(`[Performance] Executing custom Appium handler...`);
         await this.takeScreenshotAndLogCodeExecution(appiumHandler.toString());
         await appiumHandler(driver);
+        const handlerEndTime = performance.now();
         globalLogger.debug("Custom Appium handler executed successfully");
+        globalLogger.debug(`[Performance] Appium handler completed in ${(handlerEndTime - handlerStartTime).toFixed(2)}ms`);
         this.step_number++;
+        this._stats_executedSteps++;
+        const totalTime2 = performance.now() - startTime;
+        globalLogger.debug(`[Performance] aiExecute total time: ${totalTime2.toFixed(2)}ms`);
         return;
       } catch (e) {
         globalLogger.warn("Custom Appium handler failed, falling back to AI execution");
       }
     }
     if (useSmartLoop) {
-      const ctx = this.createSmartLoopContext();
+      const smartLoopStartTime = performance.now();
+      globalLogger.debug(`[Performance] Starting smart loop execution...`);
+      const ctx = this.createSmartLoopContext({ pendingLogPromises: this.pendingLogPromises });
       const result = await executeSmartLoop(ctx, {
         stepNumber: this.step_number,
         description: command,
-        instruction: command
+        instruction: command,
+        ...this.testId && {
+          filepath: this.testId
+        }
       });
+      const smartLoopEndTime = performance.now();
+      globalLogger.debug(`[Performance] Smart loop completed in ${(smartLoopEndTime - smartLoopStartTime).toFixed(2)}ms`);
       if (!result.success) {
         throw new Error(result.error || "Smart loop execution failed");
       }
+      if (result.cacheHitCount) {
+        this._stats_cacheHits += result.cacheHitCount;
+      }
       this.step_number++;
+      this._stats_executedSteps += result.iterations ?? 1;
     } else {
+      const gptHandlerStartTime = performance.now();
+      globalLogger.debug(`[Performance] Starting GPT handler execution...`);
       await this.gptHandler(command, cachingMode);
+      const gptHandlerEndTime = performance.now();
+      globalLogger.debug(`[Performance] GPT handler completed in ${(gptHandlerEndTime - gptHandlerStartTime).toFixed(2)}ms`);
     }
+    const totalTime = performance.now() - startTime;
+    globalLogger.debug(`[Performance] aiExecute total time: ${totalTime.toFixed(2)}ms`);
   }
   /**
    * Asserts a single condition using the GPTDriver.
@@ -1057,15 +1564,37 @@ class GptDriver {
    * If the assertion fails, an error is thrown.
    *
    * @param {string} assertion - The condition to be asserted.
-   * @param cachingMode - The caching mode to be used for the assertion.
+   * @param {Object} options - Optional configuration object
+   * @param {CachingMode} options.cachingMode - The caching mode to be used for the assertion.
+   * @param {boolean} options.useSmartLoop - If true, uses the smart loop execution for optimized caching. Default: false
    * @throws {Error} If the assertion fails.
+   *
+   * @example
+   * // Basic usage
+   * await driver.assert('Login button is visible');
+   *
+   * @example
+   * // With caching mode
+   * await driver.assert('Login button is visible', {
+   *   cachingMode: "FULL_SCREEN"
+   * });
+   *
+   * @example
+   * // With smart loop enabled
+   * await driver.assert('Login button is visible', {
+   *   useSmartLoop: true,
+   *   cachingMode: "FULL_SCREEN"
+   * });
    */
-  async assert(assertion, cachingMode) {
+  async assert(assertion, {
+    cachingMode,
+    useSmartLoop = false
+  }) {
     if (!this.appiumSessionStarted) {
       await this.startSession();
     }
     try {
-      const results = await this.checkBulk([assertion], cachingMode);
+      const results = await this.checkBulk([assertion], cachingMode, 2, 1e3, useSmartLoop);
       if (!Object.values(results).at(0)) {
         await this.setSessionStatus("failed");
         globalLogger.error(`Assertion failed: ${assertion}`);
@@ -1085,15 +1614,37 @@ class GptDriver {
    * If any assertion fails, an error is thrown listing all failed assertions.
    *
    * @param {string[]} assertions - An array of conditions to be asserted.
-   * @param cachingMode - The caching mode to be used for the assertions.
+   * @param {Object} options - Optional configuration object
+   * @param {CachingMode} options.cachingMode - The caching mode to be used for the assertions.
+   * @param {boolean} options.useSmartLoop - If true, uses the smart loop execution. Default: false
    * @throws {Error} If any of the assertions fail.
+   *
+   * @example
+   * // Basic usage
+   * await driver.assertBulk(['Login button is visible', 'Username field is enabled']);
+   *
+   * @example
+   * // With caching mode
+   * await driver.assertBulk(['Login button is visible'], {
+   *   cachingMode: "FULL_SCREEN"
+   * });
+   *
+   * @example
+   * // With smart loop enabled
+   * await driver.assertBulk(['Login button is visible'], {
+   *   useSmartLoop: true,
+   *   cachingMode: "FULL_SCREEN"
+   * });
    */
-  async assertBulk(assertions, cachingMode) {
+  async assertBulk(assertions, {
+    cachingMode,
+    useSmartLoop = false
+  }) {
     if (!this.appiumSessionStarted) {
       await this.startSession();
     }
     try {
-      const results = await this.checkBulk(assertions, cachingMode);
+      const results = await this.checkBulk(assertions, cachingMode, 2, 1e3, useSmartLoop);
       const failedAssertions = Object.values(results).reduce((prev, current, currentIndex) => {
         if (!current) {
           return [...prev, assertions.at(currentIndex)];
@@ -1122,14 +1673,30 @@ class GptDriver {
    * @param {CachingMode} cachingMode - The caching mode to be used for the conditions.
    * @param {number} maxRetries - The maximum number of retries if any condition fails (default: 2).
    * @param {number} retryDelayMs - The delay in milliseconds between retries (default: 1000).
+   * @param {boolean} useSmartLoop - If true, uses the smart loop execution for optimized caching. Default: false
    * @returns {Promise<Record<string, boolean>>} A promise that resolves with an object mapping each condition
    *                                             to a boolean indicating whether the condition was met.
+   *
+   * @example
+   * // Basic usage
+   * const results = await driver.checkBulk(['Login button is visible', 'Username field is enabled']);
+   * console.log(results); // { 'Login button is visible': true, 'Username field is enabled': false }
+   *
+   * @example
+   * // With smart loop enabled
+   * const results = await driver.checkBulk(
+   *   ['Login button is visible'],
+   *   "FULL_SCREEN",
+   *   2,
+   *   1000,
+   *   true
+   * );
    */
-  async checkBulk(conditions, cachingMode, maxRetries = 2, retryDelayMs = 1e3) {
+  async checkBulk(conditions, cachingMode, maxRetries = 2, retryDelayMs = 1e3, useSmartLoop = false) {
     let attempt = 0;
     let results = {};
     while (attempt <= maxRetries) {
-      results = await this._checkBulkOnce(conditions, cachingMode, attempt);
+      results = await this._checkBulkOnce(conditions, cachingMode, attempt, useSmartLoop);
       const failedConditions = Object.entries(results).filter(([_, success]) => !success).map(([key, _]) => key);
       if (failedConditions.length === 0) {
         return results;
@@ -1151,33 +1718,67 @@ class GptDriver {
    *
    * @private
    */
-  async _checkBulkOnce(conditions, cachingMode, attempt = 0) {
+  async _checkBulkOnce(conditions, cachingMode, attempt = 0, useSmartLoop = false) {
     if (!this.appiumSessionStarted) {
       await this.startSession();
     }
     globalLogger.info(`Checking conditions (attempt ${attempt}): ${conditions.join(", ")}`);
+    const pendingLogPromises = [];
     try {
-      let screenshot;
-      if (!this.useGptDriverCloud) {
-        screenshot = await this.getScreenshot(this.appiumSessionConfig);
-      }
-      const response = await axios.post(
-        `${this.gptDriverBaseUrl}/sessions/${this.gptDriverSessionId}/assert`,
-        {
-          api_key: this.apiKey,
-          base64_screenshot: screenshot,
-          assertions: conditions,
-          command: `Assert: ${JSON.stringify(conditions)}`,
-          caching_mode: cachingMode ?? this.cachingMode,
-          step_number: this.step_number
+      if (useSmartLoop) {
+        const instruction = `Assert: ${JSON.stringify(conditions)}`;
+        const middleLayerAssertFn = async (screenshot) => {
+          return await axios.post(
+            `${this.gptDriverBaseUrl}/sessions/${this.gptDriverSessionId}/assert`,
+            {
+              api_key: this.apiKey,
+              base64_screenshot: screenshot,
+              assertions: conditions,
+              command: `Assert: ${JSON.stringify(conditions)}`,
+              caching_mode: cachingMode ?? this.cachingMode,
+              step_number: this.step_number
+            }
+          );
+        };
+        const ctx = this.createSmartLoopContext({ middleLayerAssertFn, pendingLogPromises });
+        const result = await executeSmartLoop(ctx, {
+          stepNumber: this.step_number,
+          description: instruction,
+          instruction,
+          ...this.testId && {
+            filepath: this.testId
+          }
+        });
+        if (result.cacheHitCount) {
+          this._stats_cacheHits += result.cacheHitCount;
         }
-      );
-      globalLogger.debug(`Check results: ${JSON.stringify(response.data.results)}`);
-      return response.data.results;
+        this._stats_executedSteps += result.iterations ?? 1;
+        return { [instruction]: result.success };
+      } else {
+        let screenshot;
+        if (!this.useGptDriverCloud) {
+          screenshot = await this.getScreenshot(this.appiumSessionConfig);
+        }
+        const response = await axios.post(
+          `${this.gptDriverBaseUrl}/sessions/${this.gptDriverSessionId}/assert`,
+          {
+            api_key: this.apiKey,
+            base64_screenshot: screenshot,
+            assertions: conditions,
+            command: `Assert: ${JSON.stringify(conditions)}`,
+            caching_mode: cachingMode ?? this.cachingMode,
+            step_number: this.step_number
+          }
+        );
+        globalLogger.debug(`Check results: ${JSON.stringify(response.data.results)}`);
+        return response.data.results;
+      }
     } catch (e) {
       globalLogger.error("Failed to check conditions", e);
       await this.setSessionStatus("failed");
       throw e;
+    } finally {
+      await Promise.all(pendingLogPromises);
     }
   }
   /**
@@ -1270,10 +1871,12 @@ class GptDriver {
    * const result = await driver.executeFlow('tests/login-flow.json', { useSmartLoop: true });
    */
   async executeFlow(filePath, options) {
+    const flowStartTime = performance.now();
     const useSmartLoop = options?.useSmartLoop ?? false;
     const configFilePath = this.configFilePath;
     let baseDir;
     let absolutePath;
+    let parsedConfigFile;
     if (configFilePath) {
       let raw2;
       try {
@@ -1291,7 +1894,7 @@ class GptDriver {
         globalLogger.error(msg);
         throw new Error(msg);
       }
-      const parsedConfigFile = ConfigSchema.parse(json2);
+      parsedConfigFile = ConfigSchema.parse(json2);
       if (path.isAbsolute(parsedConfigFile.testDir)) {
         baseDir = parsedConfigFile.testDir;
       } else {
@@ -1346,7 +1949,7 @@ ${issues}`);
       }
       return val.data;
     };
-    const expandSteps = async (steps, inheritedParams, parentDir, stack) => {
+    const expandSteps = async (steps, inheritedParams, parentDir, stack, currentFilePath) => {
       const out = [];
       for (const step of steps) {
         if (step.type === "fileRef") {
@@ -1358,44 +1961,80 @@ ${issues}`);
           }
           visited.add(refKey);
           const child = await loadFlow(refPath);
-          const mergedParams = { ...inheritedParams, ...step.overrides ?? {} };
+          const mergedParams = { ...inheritedParams, ...child.params, ...step.overrides ?? {} };
           const childDir = path.dirname(refPath);
-          const childExpanded = await expandSteps(child.steps, mergedParams, childDir, [...stack, refKey]);
+          const childRelativePath = path.relative(baseDir, refPath).replace(/^\.\//, "");
+          const childExpanded = await expandSteps(child.steps, mergedParams, childDir, [...stack, refKey], childRelativePath);
           out.push(...childExpanded);
         } else {
-          const resolved = { ...step, __params: { ...inheritedParams } };
+          const resolved = {
+            ...step,
+            __params: { ...inheritedParams },
+            __filepath: currentFilePath
+          };
           out.push(resolved);
         }
       }
       return out;
     };
-    const effectiveParams = { ...rootFlow.params ?? {} };
-    const expandedSteps = await expandSteps(rootFlow.steps, effectiveParams, baseDir, [absolutePath]);
+    const envPath = path.join(process.cwd(), ".env");
+    let envVars = {};
+    try {
+      await promises.access(envPath);
+      const envContent = await readFile(envPath, "utf-8");
+      envVars = dotenv.parse(envContent);
+    } catch (_) {
+    }
+    const effectiveParams = { ...parsedConfigFile?.variables, ...envVars, ...rootFlow.params };
+    const rootRelativePath = path.relative(baseDir, absolutePath).replace(/^\.\//, "");
+    const expandedSteps = await expandSteps(rootFlow.steps, effectiveParams, baseDir, [absolutePath], rootRelativePath);
     if (!this.appiumSessionStarted) {
       await this.startSession();
     }
     globalLogger.info(`Executing flow '${rootFlow.name}' with ${expandedSteps.length} step(s)...`);
     let executed = 0;
+    let cacheHits = 0;
+    let lastStepWasFromFileRef = false;
+    let fileRefStepNumber = 1;
     try {
+      const screenshot = await this.getScreenshot(this.appiumSessionConfig, false);
+      const screenshotResolution = await getImageDimensions(screenshot);
       for (const step of expandedSteps) {
         const params = step.__params ?? effectiveParams;
-        const prefix = `Step #${executed + 1} [${step.type}${step.optional ? ", optional" : ""}]`;
+        const filepath = step.__filepath ?? rootRelativePath;
+        console.log("step.__filepath", step.__filepath);
+        console.log("rootRelativePath", rootRelativePath);
+        const isFromFileRef = filepath !== rootRelativePath;
+        console.log("isFromFileRef", isFromFileRef);
+        if (!lastStepWasFromFileRef && isFromFileRef) {
+          fileRefStepNumber = 1;
+        }
+        const effectiveStepNumber = isFromFileRef ? fileRefStepNumber : this.step_number;
+        const prefix = `Step #${executed + 1} (step_number: ${effectiveStepNumber}) [${step.type}${step.optional ? ", optional" : ""}] (filepath: ${filepath})`;
         try {
           switch (step.type) {
             case "ai": {
               const instruction = this.interpolateTemplate(step.instruction, params);
               globalLogger.info(`${prefix}: ${instruction}`);
               if (useSmartLoop) {
-                const ctx = this.createSmartLoopContext();
+                const ctx = this.createSmartLoopContext({ pendingLogPromises: this.pendingLogPromises });
                 const result = await executeSmartLoop(ctx, {
-                  stepNumber: this.step_number,
+                  stepNumber: effectiveStepNumber,
                   description: instruction,
-                  instruction
+                  instruction,
+                  filepath
                 });
                 if (!result.success) {
                   throw new Error(result.error || "Smart loop execution failed");
                 }
-                this.step_number++;
+                if (result.cacheHit) {
+                  cacheHits++;
+                }
+                if (isFromFileRef) {
+                  fileRefStepNumber++;
+                } else {
+                  this.step_number++;
+                }
               } else {
                 await this.aiExecute({ command: instruction });
               }
@@ -1408,16 +2047,24 @@ ${issues}`);
               }
               globalLogger.info(`${prefix}: ${description}`);
               if (useSmartLoop) {
-                const ctx = this.createSmartLoopContext();
+                const ctx = this.createSmartLoopContext({ pendingLogPromises: this.pendingLogPromises });
                 const result = await executeSmartLoop(ctx, {
-                  stepNumber: this.step_number,
+                  stepNumber: effectiveStepNumber,
                   description,
-                  instruction: description
+                  instruction: description,
+                  filepath
                 });
                 if (!result.success) {
                   throw new Error(result.error || "Smart loop execution failed");
                 }
-                this.step_number++;
+                if (result.cacheHit) {
+                  cacheHits++;
+                }
+                if (isFromFileRef) {
+                  fileRefStepNumber++;
+                } else {
+                  this.step_number++;
+                }
               } else {
                 await this.aiExecute({ command: description });
               }
@@ -1431,16 +2078,24 @@ ${issues}`);
               globalLogger.info(`${prefix}: ${description}`);
               if (useSmartLoop) {
                 const instruction = `Verify that: ${description}`;
-                const ctx = this.createSmartLoopContext();
+                const ctx = this.createSmartLoopContext({ pendingLogPromises: this.pendingLogPromises });
                 const result = await executeSmartLoop(ctx, {
-                  stepNumber: this.step_number,
+                  stepNumber: effectiveStepNumber,
                   description,
-                  instruction
+                  instruction,
+                  filepath
                 });
                 if (!result.success) {
                   throw new Error(result.error || "Smart loop execution failed");
                 }
-                this.step_number++;
+                if (result.cacheHit) {
+                  cacheHits++;
+                }
+                if (isFromFileRef) {
+                  fileRefStepNumber++;
+                } else {
+                  this.step_number++;
+                }
               } else {
                 await this.assert(description);
               }
@@ -1449,35 +2104,98 @@ ${issues}`);
             case "type": {
               const text = this.interpolateTemplate(step.text, params);
               globalLogger.info(`${prefix}: Type text`);
-              await this.takeScreenshotAndLogCodeExecution(`type: text=${text}`);
+              this.takeScreenshotAndLogCodeExecution(`type: text=${text}`);
               await this.performType(text);
-              this.step_number++;
+              if (isFromFileRef) {
+                fileRefStepNumber++;
+              } else {
+                this.step_number++;
+              }
               break;
             }
-            case "scroll": {
-              globalLogger.info(`${prefix}: Scroll ${step.direction}`);
-              await this.takeScreenshotAndLogCodeExecution(`scroll: direction=${step.direction}`);
-              await this.performScroll(step.direction);
-              this.step_number++;
+            case "enter": {
+              globalLogger.info(`${prefix}: Press Enter`);
+              this.takeScreenshotAndLogCodeExecution(`press: Enter`);
+              await this.performPressEnter();
+              if (step.delayNextStep) {
+                await this._delay(step.delayNextStep);
+              }
+              if (isFromFileRef) {
+                fileRefStepNumber++;
+              } else {
+                this.step_number++;
+              }
+              break;
+            }
+            case "scroll":
+            case "swipe": {
+              const description = step.descriptionText ? this.interpolateTemplate(step.descriptionText, params) : void 0;
+              if (description && useSmartLoop) {
+                globalLogger.info(`${prefix}: ${description}`);
+                const ctx = this.createSmartLoopContext({ pendingLogPromises: this.pendingLogPromises });
+                const result = await executeSmartLoop(ctx, {
+                  stepNumber: effectiveStepNumber,
+                  description,
+                  instruction: description,
+                  filepath
+                });
+                if (!result.success) {
+                  throw new Error(result.error || "Smart loop execution failed");
+                }
+                if (result.cacheHit) {
+                  cacheHits++;
+                }
+                if (isFromFileRef) {
+                  fileRefStepNumber++;
+                } else {
+                  this.step_number++;
+                }
+              } else {
+                globalLogger.info(`${prefix}: ${step.type} ${step.direction}`);
+                this.takeScreenshotAndLogCodeExecution(`${step.type}: direction=${step.direction}`);
+                await this.performSwipe({
+                  direction: step.direction,
+                  x1: step.x1,
+                  y1: step.y1,
+                  x2: step.x2,
+                  y2: step.y2,
+                  duration: step.duration,
+                  screenshotHeight: screenshotResolution.height,
+                  screenshotWidth: screenshotResolution.width
+                });
+                if (isFromFileRef) {
+                  fileRefStepNumber++;
+                } else {
+                  this.step_number++;
+                }
+              }
               break;
             }
             case "zoom": {
               globalLogger.info(`${prefix}: Zoom ${step.direction}`);
-              await this.takeScreenshotAndLogCodeExecution(`zoom: direction=${step.direction}`);
-              this.step_number++;
+              this.takeScreenshotAndLogCodeExecution(`zoom: direction=${step.direction}`);
+              if (isFromFileRef) {
+                fileRefStepNumber++;
+              } else {
+                this.step_number++;
+              }
               break;
             }
             case "scrollUntil": {
               const interpolatedText = step.text != null ? this.interpolateTemplate(step.text, params) : void 0;
               globalLogger.info(`${prefix}: Scroll until ${interpolatedText ?? step.elementId}`);
-              await this.takeScreenshotAndLogCodeExecution(`scrollUntil: text=${interpolatedText}, elementId=${step.elementId}`);
+              this.takeScreenshotAndLogCodeExecution(`scrollUntil: text=${interpolatedText}, elementId=${step.elementId}`);
               await this.performScrollUntil({
                 direction: step.direction,
                 text: interpolatedText,
                 elementId: step.elementId,
                 maxScrolls: step.maxScrolls
               });
-              this.step_number++;
+              if (isFromFileRef) {
+                fileRefStepNumber++;
+              } else {
+                this.step_number++;
+              }
               break;
             }
             case "deeplink": {
@@ -1485,7 +2203,7 @@ ${issues}`);
               const bundleId = params["bundleId"];
               const url = this.interpolateTemplate(step.url, params);
               globalLogger.info(`${prefix}: Open deeplink ${url}`);
-              await this.takeScreenshotAndLogCodeExecution(`openDeepLinkUrl: url=${url}`);
+              this.takeScreenshotAndLogCodeExecution(`openDeepLinkUrl: url=${url}`);
               await this.openDeepLinkUrl({ url, package: pkg, bundleId });
               break;
             }
@@ -1493,10 +2211,12 @@ ${issues}`);
               throw new Error(`Unsupported step type at execution: ${step.type}`);
             }
           }
+          lastStepWasFromFileRef = isFromFileRef;
           executed++;
         } catch (err) {
           if (step.optional) {
             globalLogger.warn(`${prefix} failed but marked optional. Continuing. Error: ${err.message}`);
+            lastStepWasFromFileRef = isFromFileRef;
             continue;
           }
           throw err;
@@ -1509,6 +2229,16 @@ ${issues}`);
       }
       throw e;
     }
+    const flowEndTime = performance.now();
+    const totalTime = (flowEndTime - flowStartTime) / 1e3;
+    globalLogger.info(`
+${"=".repeat(50)}`);
+    globalLogger.info(`Flow Execution Summary:`);
+    globalLogger.info(`Total Test Time: ${totalTime.toFixed(2)} seconds`);
+    globalLogger.info(`Total Steps executed: ${executed}`);
+    globalLogger.info(`Total Step Cache Hits: ${cacheHits}`);
+    globalLogger.info(`${"=".repeat(50)}
+`);
     return rootFlow;
   }
   async gptHandler(command, cachingMode) {
@@ -1516,8 +2246,15 @@ ${issues}`);
       let conditionSucceeded = false;
       while (!conditionSucceeded) {
         let screenshot;
+        let originalScreenshotBase64 = null;
         if (!this.useGptDriverCloud) {
-          screenshot = await this.getScreenshot(this.appiumSessionConfig);
+          const stabilityResult = await waitForStableScreen(
+            () => this.getScreenshot(this.appiumSessionConfig)
+          );
+          screenshot = stabilityResult.originalScreenshotBase64;
+          if (!stabilityResult.stable) {
+            globalLogger.warn("Screen did not stabilize within timeout, proceeding with last screenshot");
+          }
         }
         globalLogger.info("Requesting next action from GPT Driver...");
         const response = await axios.request(
@@ -1545,7 +2282,6 @@ ${issues}`);
         for (const appiumCommand of executeResponse.commands) {
           await this.executeCommand(appiumCommand);
         }
-        await delay(1500);
       }
       this.step_number = this.step_number + 1;
       globalLogger.info("Command execution completed successfully");
@@ -1573,13 +2309,13 @@ ${issues}`);
       });
     }
   }
-  async logCodeExecution(screenshot, command) {
+  async logCodeExecution(screenshot, command, isCacheHit) {
     try {
-      const screenshot2 = await this.getScreenshot(this.appiumSessionConfig);
       await axios.post(`${this.gptDriverBaseUrl}/sessions/${this.gptDriverSessionId}/log_code_execution`, {
         api_key: this.apiKey,
-        base64_screenshot: screenshot2,
-        command
+        base64_screenshot: screenshot,
+        command,
+        from_cache: !!isCacheHit
       });
     } catch (e) {
       globalLogger.error("Failed to log code execution", e);