gpt-driver-node 1.0.3 → 1.0.5

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';
@@ -91,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(),
@@ -123,9 +194,8 @@ const SavableSwipeStepSchema = SavableStepBaseSchema.extend({
   y2: z.number().optional(),
   duration: z.number().optional().default(500)
 });
-const SavableScrollStepSchema = SavableStepBaseSchema.extend({
-  type: z.literal("scroll"),
-  direction: z.enum(["up", "down"])
+const SavableScrollStepSchema = SavableSwipeStepSchema.extend({
+  type: z.literal("scroll")
 });
 const SavableZoomStepSchema = SavableStepBaseSchema.extend({
   type: z.literal("zoom"),
@@ -146,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(),
@@ -170,6 +244,8 @@ const SavableStepSchema = z.discriminatedUnion("type", [
   // type: 'deeplink'
   SavableAIStepSchema,
   // type: 'ai'
+  SavableEnterStepSchema,
+  // type: 'enter'
   SavableFileRefStepSchema
   // type: 'fileRef'
 ]);
@@ -191,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) {
@@ -275,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,
@@ -292,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
       };
     }));
@@ -310,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 };
   }
@@ -442,6 +531,10 @@ 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:");
 }
@@ -459,8 +552,8 @@ function parseSlideCommand(cmd) {
   const directionMap = {
     down: "up",
     up: "down",
-    left: "right",
-    right: "left"
+    left: "left",
+    right: "right"
   };
   return {
     direction: directionMap[extractedDirection],
@@ -477,22 +570,38 @@ 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;
-      const firstScreenshot = await ctx.getScreenshot();
-      const screenshotResolution = await getImageDimensions(firstScreenshot);
+      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,
@@ -503,11 +612,14 @@ async function executeSmartLoop(ctx, params) {
             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;
           }
@@ -519,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);
@@ -540,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;
@@ -577,6 +728,10 @@ async function executeSmartLoop(ctx, params) {
             );
             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) {
@@ -589,6 +744,9 @@ async function executeSmartLoop(ctx, params) {
           if (direction) {
             globalLogger.debug(`[SmartLoop] Scrolling ${direction}`);
             await ctx.performSwipe({ direction });
+            if (isCacheHit) {
+              await delay(650);
+            }
             actionExecuted = true;
           }
         } else if (isSlideCommand(cmd)) {
@@ -626,6 +784,9 @@ async function executeSmartLoop(ctx, params) {
               screenshotHeight: screenshotResolution.height,
               duration: 500
             });
+            if (isCacheHit) {
+              await delay(650);
+            }
             actionExecuted = true;
           }
         } else if (isTypeCommand(cmd)) {
@@ -638,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: screenshotResolution,
-              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
     };
   }
 }
@@ -711,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.
    *
@@ -785,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;
@@ -884,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.
    *
@@ -896,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`,
@@ -912,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
   // ─────────────────────────────────────────────────────────────────────────────
@@ -919,7 +1172,7 @@ 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");
     }
@@ -931,8 +1184,11 @@ class GptDriver {
       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
     };
   }
   /**
@@ -1033,6 +1289,24 @@ class GptDriver {
       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));
   }
@@ -1160,14 +1434,43 @@ class GptDriver {
   }
   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" && 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();
-      screenshot = transformedImage.toString("base64");
+    let screenshot;
+    if (appiumSessionConfig.platform === "Android") {
+      try {
+        const { execSync } = await import('node:child_process');
+        let udid;
+        if (this.driver) {
+          if (this.driver.sessionId != null) {
+            const caps = this.driver.capabilities;
+            udid = caps["appium:udid"] || caps["udid"];
+          } else {
+            const driver = this.driver;
+            const capabilities = await driver.getCapabilities();
+            udid = capabilities.get("appium:udid") || capabilities.get("udid");
+          }
+        }
+        const deviceArg = udid ? `-s ${udid}` : "";
+        const buffer = execSync(`adb ${deviceArg} exec-out screencap -p`, {
+          encoding: "buffer",
+          maxBuffer: 50 * 1024 * 1024
+        });
+        screenshot = buffer.toString("base64");
+      } catch (e) {
+        globalLogger.warn("ADB screenshot failed, falling back to Appium screenshot");
+        const url = buildUrl(this.appiumSessionConfig.serverUrl, `/session/${this.appiumSessionConfig.id}/screenshot`);
+        const screenshotResponse = await axios.get(url);
+        screenshot = screenshotResponse.data.value;
+      }
+    } else {
+      const url = buildUrl(this.appiumSessionConfig.serverUrl, `/session/${this.appiumSessionConfig.id}/screenshot`);
+      const screenshotResponse = await axios.get(url);
+      screenshot = screenshotResponse.data.value;
+      if (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();
+        screenshot = transformedImage.toString("base64");
+      }
     }
     return screenshot;
   }
@@ -1217,41 +1520,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.
@@ -1260,15 +1593,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}`);
@@ -1288,15 +1643,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)];
@@ -1325,14 +1702,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;
@@ -1354,33 +1747,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);
     }
   }
   /**
@@ -1473,10 +1900,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 {
@@ -1494,7 +1923,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 {
@@ -1561,7 +1990,7 @@ ${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 childRelativePath = path.relative(baseDir, refPath).replace(/^\.\//, "");
           const childExpanded = await expandSteps(child.steps, mergedParams, childDir, [...stack, refKey], childRelativePath);
@@ -1577,7 +2006,15 @@ ${issues}`);
       }
       return out;
     };
-    const effectiveParams = { ...rootFlow.params ?? {} };
+    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) {
@@ -1585,20 +2022,33 @@ ${issues}`);
     }
     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 filepath = step.__filepath ?? rootRelativePath;
-        const prefix = `Step #${executed + 1} [${step.type}${step.optional ? ", optional" : ""}] (filepath: ${filepath})`;
+        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,
                   filepath
@@ -1606,7 +2056,14 @@ ${issues}`);
                 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 });
               }
@@ -1619,9 +2076,9 @@ ${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,
                   filepath
@@ -1629,7 +2086,14 @@ ${issues}`);
                 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 });
               }
@@ -1643,9 +2107,9 @@ ${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,
                   filepath
@@ -1653,7 +2117,14 @@ ${issues}`);
                 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);
               }
@@ -1662,9 +2133,27 @@ ${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 "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":
@@ -1672,9 +2161,9 @@ ${issues}`);
               const description = step.descriptionText ? this.interpolateTemplate(step.descriptionText, params) : void 0;
               if (description && useSmartLoop) {
                 globalLogger.info(`${prefix}: ${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: description,
                   filepath
@@ -1682,43 +2171,60 @@ ${issues}`);
                 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 {
                 globalLogger.info(`${prefix}: ${step.type} ${step.direction}`);
-                await this.takeScreenshotAndLogCodeExecution(`${step.type}: direction=${step.direction}`);
-                if (step.type === "swipe") {
-                  await this.performSwipe({
-                    direction: step.direction,
-                    x1: step.x1,
-                    y1: step.y1,
-                    x2: step.x2,
-                    y2: step.y2,
-                    duration: step.duration
-                  });
+                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 {
-                  await this.performSwipe({ direction: step.direction });
+                  this.step_number++;
                 }
-                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": {
@@ -1726,7 +2232,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;
             }
@@ -1734,10 +2240,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;
@@ -1750,6 +2258,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) {
@@ -1757,8 +2275,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(
@@ -1786,7 +2311,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");
@@ -1814,13 +2338,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);