@loadmill/droid-cua 2.12.0 → 2.14.0

package/build/src/browser/connection.js

@@ -28,6 +28,12 @@ export async function navigateToUrl(browserSessionId, url) {
     }
     return currentBackend.navigateToUrl(browserSessionId, url);
 }
+export async function closeCurrentTab(browserSessionId) {
+    if (!currentBackend?.closeCurrentTab) {
+        throw new Error("Active browser backend does not support closing browser tabs.");
+    }
+    return currentBackend.closeCurrentTab(browserSessionId);
+}
 export { getCurrentPlatform };
 export async function disconnect() {
     if (currentBackend?.disconnect) {

package/build/src/browser/factory.js

@@ -10,6 +10,7 @@ export function getBrowserBackend(_platform = "browser") {
         getBrowserInfo: browserConnection.getBrowserInfo,
         getScreenshotAsBase64: browserConnection.getScreenshotAsBase64,
         navigateToUrl: browserConnection.navigateToUrl,
+        closeCurrentTab: browserConnection.closeCurrentTab,
         handleModelAction: browserActions.handleModelAction,
         disconnect: browserConnection.disconnect,
     };

package/build/src/browser/playwright/connection.js

@@ -4,7 +4,7 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { emitDesktopDebug } from "../../utils/desktop-debug.js";
 import { requireInstalledBrowser } from "./installed-browser.js";
-import { clearActiveBrowserSession, getActiveBrowserSession, setActiveBrowserSession } from "./session-state.js";
+import { clearActiveBrowserSession, getActiveBrowserSession, getSessionActiveBrowserPage, setActiveBrowserSession } from "./session-state.js";
 import { normalizeAutomationUrl, normalizeOptionalAutomationUrl } from "./url.js";
 import { getWelcomePageUrl, isWelcomePageUrl } from "./welcome-page.js";
 const DEFAULT_VIEWPORT = { width: 1440, height: 900 };
@@ -77,6 +77,62 @@ function isCurrentSession(session) {
         return false;
     }
 }
+function pageIsClosed(page) {
+    try {
+        return typeof page?.isClosed === "function" && page.isClosed();
+    }
+    catch {
+        return false;
+    }
+}
+function getActivePage(session) {
+    return getSessionActiveBrowserPage(session);
+}
+async function bringPageToFront(page) {
+    if (typeof page?.bringToFront !== "function") {
+        return;
+    }
+    try {
+        await page.bringToFront();
+    }
+    catch {
+        // Best-effort only. The logical active tab is still tracked in pageStack.
+    }
+}
+function pruneClosedPages(session) {
+    session.pageStack = session.pageStack.filter((page) => !pageIsClosed(page));
+}
+function trackPage(session, page) {
+    if (!page || session.pageStack.includes(page)) {
+        return;
+    }
+    page.on?.("close", () => {
+        handleTrackedPageClosed(session, page);
+    });
+    session.pageStack.push(page);
+    void bringPageToFront(page);
+}
+function handleTrackedPageClosed(session, page) {
+    if (session.disconnecting) {
+        return;
+    }
+    if (page === session._rootPage) {
+        handleExternalSessionClosed(session, "page_closed");
+        return;
+    }
+    const wasActive = getActivePage(session) === page;
+    session.pageStack = session.pageStack.filter((stackedPage) => stackedPage !== page);
+    pruneClosedPages(session);
+    if (wasActive) {
+        const restoredPage = getActivePage(session);
+        void bringPageToFront(restoredPage);
+        emitDesktopDebug("browser.popup", "device", { sessionId: session.sessionId }, {
+            stage: "closed",
+            restoredUrl: restoredPage?.url?.() || null,
+            stackDepth: session.pageStack.length,
+        });
+    }
+}
 async function waitForPendingBrowserSessionShutdown() {
     if (!pendingBrowserSessionShutdown) {
         return;
@@ -267,21 +323,15 @@ export async function connectToBrowser(targetOrOptions) {
     const welcomePageUrl = await getWelcomePageUrl();
     const initialUrl = normalizedUrl || welcomePageUrl;
     await closeExtraPages(context, primaryPage);
-    context.on("page", (page) => {
-        if (page === primaryPage) {
-            return;
-        }
-        console.warn("New tab or popup opened. Automation will remain attached to the original page only.");
-        emitDesktopDebug("browser.popup", "device", { sessionId }, {
-            stage: "opened",
-            url: page.url() || null,
-        });
-    });
-    await gotoWithTimeoutTolerance(primaryPage, initialUrl);
     const session = {
         sessionId,
         context,
-        page: primaryPage,
+        _rootPage: primaryPage,
+        get page() {
+            return getActivePage(this);
+        },
+        pageStack: [primaryPage],
+        pageUrls: new WeakMap([[primaryPage, normalizedUrl]]),
         url: normalizedUrl,
         welcomePageUrl,
         sessionMode: options.sessionMode,
@@ -293,10 +343,22 @@ export async function connectToBrowser(targetOrOptions) {
         externalDisconnectNotified: false,
         shutdownPromise: null,
     };
-    setActiveBrowserSession(session);
     primaryPage.on?.("close", () => {
-        handleExternalSessionClosed(session, "page_closed");
+        handleTrackedPageClosed(session, primaryPage);
+    });
+    context.on("page", (page) => {
+        if (page === primaryPage) {
+            return;
+        }
+        trackPage(session, page);
+        emitDesktopDebug("browser.popup", "device", { sessionId }, {
+            stage: "opened",
+            url: page.url() || null,
+            stackDepth: session.pageStack.length,
+        });
     });
+    await gotoWithTimeoutTolerance(primaryPage, initialUrl);
+    setActiveBrowserSession(session);
     context.on?.("close", () => {
         handleExternalSessionClosed(session, "context_closed");
     });
@@ -313,18 +375,21 @@ export async function connectToBrowser(targetOrOptions) {
 }
 export async function getBrowserInfo(browserSessionId) {
     const session = getActiveBrowserSession(browserSessionId);
-    const currentUrl = normalizeKnownPageUrl(session.page.url()) || session.url || null;
+    const activePage = getActivePage(session);
+    const currentUrl = normalizeKnownPageUrl(activePage.url()) || session.pageUrls.get(activePage) || null;
     return buildSessionBrowserInfo(currentUrl, session.installedBrowser);
 }
 export async function getScreenshotAsBase64(browserSessionId) {
     const session = getActiveBrowserSession(browserSessionId);
-    const imageBuffer = await session.page.screenshot({ type: "png" });
+    const imageBuffer = await getActivePage(session).screenshot({ type: "png" });
     return imageBuffer.toString("base64");
 }
 export async function navigateToUrl(browserSessionId, url) {
     const session = getActiveBrowserSession(browserSessionId);
     const normalizedUrl = normalizeAutomationUrl(url);
-    await gotoWithTimeoutTolerance(session.page, normalizedUrl);
+    const activePage = getActivePage(session);
+    await gotoWithTimeoutTolerance(activePage, normalizedUrl);
+    session.pageUrls.set(activePage, normalizedUrl);
     session.url = normalizedUrl;
     emitDesktopDebug("browser.navigate", "device", { browserSessionId }, {
         platform: "browser",
@@ -332,6 +397,40 @@ export async function navigateToUrl(browserSessionId, url) {
     });
     return normalizedUrl;
 }
+export async function closeCurrentTab(browserSessionId) {
+    const session = getActiveBrowserSession(browserSessionId);
+    pruneClosedPages(session);
+    const activePage = getActivePage(session);
+    const previousPage = session.pageStack.length > 1
+        ? session.pageStack[session.pageStack.length - 2]
+        : null;
+    if (!activePage || activePage === session._rootPage || !previousPage) {
+        return {
+            closed: false,
+            restoredUrl: normalizeKnownPageUrl(activePage?.url?.()) || session.pageUrls.get(activePage) || null,
+            message: "No previous browser tab is available. The current tab was left open.",
+        };
+    }
+    await activePage.close();
+    if (session.pageStack.includes(activePage)) {
+        handleTrackedPageClosed(session, activePage);
+    }
+    const restoredPage = getActivePage(session);
+    const restoredUrl = normalizeKnownPageUrl(restoredPage?.url?.()) || session.pageUrls.get(restoredPage) || null;
+    emitDesktopDebug("browser.tab.close_current", "device", { browserSessionId }, {
+        platform: "browser",
+        closed: true,
+        restoredUrl,
+        stackDepth: session.pageStack.length,
+    });
+    return {
+        closed: true,
+        restoredUrl,
+        message: restoredUrl
+            ? `Closed current tab. Returned to ${restoredUrl}.`
+            : "Closed current tab. Returned to the previous browser tab.",
+    };
+}
 export async function disconnect() {
     let session;
     try {

package/build/src/browser/playwright/session-state.js

@@ -14,6 +14,13 @@ export function getActiveBrowserSession(browserSessionId = null) {
     }
     return activeSession;
 }
+export function getSessionActiveBrowserPage(session) {
+    const stack = Array.isArray(session?.pageStack) ? session.pageStack : [];
+    if (stack.length > 0) {
+        return stack[stack.length - 1];
+    }
+    return session?._rootPage || session?.page;
+}
 export function getActiveBrowserPage(browserSessionId = null) {
-    return getActiveBrowserSession(browserSessionId).page;
+    return getSessionActiveBrowserPage(getActiveBrowserSession(browserSessionId));
 }

package/build/src/core/execution-engine.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { getScreenshotAsBase64, getCurrentPlatform } from "../device/connection.js";
-import { getBrowserInfo, navigateToUrl as navigateBrowserToUrl } from "../browser/connection.js";
+import { closeCurrentTab as closeCurrentBrowserTab, getBrowserInfo, navigateToUrl as navigateBrowserToUrl } from "../browser/connection.js";
 import { handleModelAction } from "../device/actions.js";
 import { sendCUARequest } from "../device/openai.js";
 import { executeLoadmillInstruction } from "../device/loadmill.js";
@@ -11,6 +11,7 @@ import { CAPTURE_SOURCES } from "./capture-sources.js";
 import { ScreenshotStore } from "./screenshot-store.js";
 import { handlePreviewClick } from "./tool-handlers/preview-click.js";
 import { handleNavigateToolCall } from "./tool-handlers/navigate.js";
+import { handleCloseCurrentTabToolCall } from "./tool-handlers/close-current-tab.js";
 import { handleAssertionToolCall } from "./tool-handlers/assert.js";
 import { handleLoadmillToolCall } from "./tool-handlers/loadmill.js";
 import { handleTestDesignCompleteToolCall } from "./tool-handlers/test-design-complete.js";
@@ -73,6 +74,7 @@ export class ExecutionEngine {
         this.getCurrentPlatform = options.getCurrentPlatform || getCurrentPlatform;
         this.getBrowserInfo = options.getBrowserInfo || getBrowserInfo;
         this.navigateToUrl = options.navigateToUrl || navigateBrowserToUrl;
+        this.closeCurrentTab = options.closeCurrentTab || closeCurrentBrowserTab;
         this.executeLoadmillInstruction = options.executeLoadmillInstruction || executeLoadmillInstruction;
         this.toolCapabilities = options.toolCapabilities || {};
         this.baseSystemPrompt = options.baseSystemPrompt || session?.systemPrompt || null;
@@ -102,6 +104,8 @@ export class ExecutionEngine {
                 return await handleAssertionToolCall(handlerArgs);
             case "navigate":
                 return await handleNavigateToolCall(handlerArgs);
+            case "close_current_tab":
+                return await handleCloseCurrentTabToolCall(handlerArgs);
             case "loadmill":
                 return await handleLoadmillToolCall(handlerArgs);
             case "test_design_complete":

package/build/src/core/tool-handlers/browser-session.js

@@ -0,0 +1,7 @@
+export function updateBrowserSessionInfo(session, browserInfo, fallbackUrl = null) {
+    session.browserInfo = browserInfo;
+    session.deviceInfo = browserInfo;
+    session.currentUrl = browserInfo.currentUrl || fallbackUrl || null;
+    session.browserName = browserInfo.browserName || session.currentUrl;
+    session.deviceName = session.browserName;
+}

package/build/src/core/tool-handlers/close-current-tab.js

@@ -0,0 +1,53 @@
+import { normalizeBrowserInfoForSession } from "../../browser/normalize.js";
+import { CAPTURE_SOURCES } from "../capture-sources.js";
+import { printCliOutput } from "../../utils/console-output.js";
+import { updateBrowserSessionInfo } from "./browser-session.js";
+import { buildFunctionCallOutputItem, buildPreviewOutputContent, buildTextToolOutputItem, } from "./utils.js";
+export async function handleCloseCurrentTabToolCall({ engine, callId, context = null, stepContext = null }) {
+    const session = engine.session;
+    if (session?.targetKind !== "browser" && session?.deviceInfo?.platform !== "browser") {
+        return {
+            kind: "continue",
+            outputItem: buildTextToolOutputItem(callId, "close_current_tab is only supported for web runs."),
+        };
+    }
+    const addOutput = context?.addOutput || printCliOutput;
+    const result = await engine.closeCurrentTab(session.browserSessionId);
+    if (!result.closed) {
+        return {
+            kind: "continue",
+            outputItem: buildTextToolOutputItem(callId, result.message || "No previous browser tab is available. The current tab was left open."),
+        };
+    }
+    addOutput({
+        type: "action",
+        text: "Close current tab",
+        eventType: "tool_call",
+        runId: context?.runId,
+        stepId: stepContext?.stepId,
+        instructionIndex: stepContext?.instructionIndex,
+        payload: {
+            platform: session.deviceInfo?.platform,
+            toolName: "close_current_tab",
+            restoredUrl: result.restoredUrl,
+        },
+    });
+    const browserInfo = normalizeBrowserInfoForSession(await engine.getBrowserInfo(session.browserSessionId));
+    updateBrowserSessionInfo(session, browserInfo, result.restoredUrl);
+    const screenshotBase64 = await engine.getScreenshotAsBase64(session.deviceId, session.deviceInfo);
+    const currentScreenshot = await engine.recordScreenshot(screenshotBase64, {
+        runId: context?.runId,
+        sessionId: context?.sessionId,
+        stepId: stepContext?.stepId,
+        instructionIndex: stepContext?.instructionIndex,
+        captureSource: CAPTURE_SOURCES.CALL_OUTPUT_POST_ACTION,
+    });
+    return {
+        kind: "continue",
+        outputItem: buildFunctionCallOutputItem(callId, buildPreviewOutputContent({
+            text: result.message,
+            annotatedScreenshotBase64: screenshotBase64,
+        })),
+        currentScreenshot,
+    };
+}

package/build/src/core/tool-handlers/navigate.js

@@ -2,6 +2,7 @@ import { normalizeBrowserInfoForSession } from "../../browser/normalize.js";
 import { buildExecutionNavigationRecoveryPrompt } from "../../prompts/execution.js";
 import { emitDesktopDebug } from "../../utils/desktop-debug.js";
 import { printCliOutput } from "../../utils/console-output.js";
+import { updateBrowserSessionInfo } from "./browser-session.js";
 import { buildDebugContext, buildFunctionCallOutputItem, buildPreviewOutputContent, buildTextToolOutputItem, isDesignContext, parseStringToolArgument, } from "./utils.js";
 export async function handleNavigateToolCall({ engine, callId, argumentsText, context = null, stepContext = null }) {
     const session = engine.session;
@@ -42,11 +43,7 @@ export async function handleNavigateToolCall({ engine, callId, argumentsText, co
     try {
         const normalizedUrl = await engine.navigateToUrl(session.browserSessionId, navigationTarget);
         const browserInfo = normalizeBrowserInfoForSession(await engine.getBrowserInfo(session.browserSessionId));
-        session.browserInfo = browserInfo;
-        session.deviceInfo = browserInfo;
-        session.currentUrl = browserInfo.currentUrl || normalizedUrl;
-        session.browserName = browserInfo.browserName || session.currentUrl;
-        session.deviceName = session.browserName;
+        updateBrowserSessionInfo(session, browserInfo, normalizedUrl);
         emitDesktopDebug("runner.navigate.completed", isDesignContext(context) ? "design" : "execution", buildDebugContext(context, stepContext), {
             instruction: navigationTarget,
             target: navigationTarget,

package/build/src/core/tool-handlers/test-design-complete.js

@@ -60,7 +60,7 @@ export async function handleTestDesignCompleteToolCall({ engine, callId, argumen
     const addOutput = context?.addOutput || printCliOutput;
     addOutput({
         type: "success",
-        text: "Design exploration complete. Generating final test script...",
+        text: "Design exploration complete. Generating test script.",
         eventType: "tool_call",
         runId: context?.runId,
         stepId: stepContext?.stepId,

package/build/src/device/android/connection.js

@@ -3,6 +3,8 @@ import sharp from "sharp";
 import { logger } from "../../utils/logger.js";
 import { emitDesktopDebug } from "../../utils/desktop-debug.js";
 import { execAdb, execEmulator, spawnAdb, spawnEmulator } from "./tools.js";
+const AVD_READY_TIMEOUT_MS = 180000;
+const AVD_READY_TIMEOUT_SECONDS = AVD_READY_TIMEOUT_MS / 1000;
 async function listConnectedDevices() {
     const { stdout } = await execAdb(["devices"]);
     return stdout
@@ -65,6 +67,12 @@ async function waitForWindowServiceReady(deviceId, timeoutMs = 60000) {
     }
     return false;
 }
+function remainingTimeoutMs(deadline) {
+    return Math.max(0, deadline - Date.now());
+}
+function emulatorLaunchTimeoutError() {
+    return new Error(`Emulator launch timed out after ${AVD_READY_TIMEOUT_SECONDS}s. Check AVD health and retry.`);
+}
 async function findRunningEmulatorByAvdName(avdName) {
     const devices = await listConnectedDevices();
     const readyEmulators = devices.filter((entry) => entry.state === "device" && entry.id.startsWith("emulator-"));
@@ -76,7 +84,8 @@ async function findRunningEmulatorByAvdName(avdName) {
     }
     return null;
 }
-async function launchAndWaitForAvd(avdName, timeoutMs = 60000) {
+async function launchAndWaitForAvd(avdName, timeoutMs = AVD_READY_TIMEOUT_MS, options = {}) {
+    const log = options.log || console.log;
     let avdExists = false;
     try {
         const { stdout } = await execEmulator(["-list-avds"]);
@@ -92,7 +101,7 @@ async function launchAndWaitForAvd(avdName, timeoutMs = 60000) {
     }
     const baseline = await listConnectedDevices();
     const baselineReadyEmulators = new Set(baseline.filter((entry) => entry.state === "device" && entry.id.startsWith("emulator-")).map((entry) => entry.id));
-    console.log(`Launching Android emulator "${avdName}"...`);
+    log(`Launching Android emulator "${avdName}"...`);
     const emulatorProcess = spawnEmulator(["-avd", avdName], { detached: true, stdio: "ignore" });
     emulatorProcess.unref();
     const deadline = Date.now() + timeoutMs;
@@ -108,9 +117,10 @@ async function launchAndWaitForAvd(avdName, timeoutMs = 60000) {
         }
         await wait(2000);
     }
-    throw new Error("Emulator launch timed out after 60s. Check AVD health and retry.");
+    throw emulatorLaunchTimeoutError();
 }
-export async function connectToDevice(deviceTargetId) {
+export async function connectToDevice(deviceTargetId, options = {}) {
+    const log = options.log || console.log;
     emitDesktopDebug("device.connect", "device", {}, { platform: "android", stage: "start", targetId: deviceTargetId || null });
     const parsedTarget = parseTargetToken(deviceTargetId || "");
     const devices = await listConnectedDevices();
@@ -126,27 +136,28 @@ export async function connectToDevice(deviceTargetId) {
             throw new Error("No ready Android devices found. Connect a device (or start an emulator), authorize adb, and retry.");
         }
         const selected = readyDevices[0].id;
-        console.log(`Using connected Android device: ${selected}`);
+        log(`Using connected Android device: ${selected}`);
         emitDesktopDebug("device.connect", "device", {}, { platform: "android", stage: "success", deviceId: selected, reused: true });
         return selected;
     }
     if (parsedTarget.kind === "avd") {
+        const deadline = Date.now() + AVD_READY_TIMEOUT_MS;
         const alreadyRunning = await findRunningEmulatorByAvdName(parsedTarget.avdName);
         if (alreadyRunning) {
-            const ready = await waitForWindowServiceReady(alreadyRunning, 60000);
+            const ready = await waitForWindowServiceReady(alreadyRunning, remainingTimeoutMs(deadline));
             if (!ready) {
-                throw new Error("Emulator launch timed out after 60s. Check AVD health and retry.");
+                throw emulatorLaunchTimeoutError();
             }
-            console.log(`Using already-running emulator for AVD "${parsedTarget.avdName}": ${alreadyRunning}`);
+            log(`Using already-running emulator for AVD "${parsedTarget.avdName}": ${alreadyRunning}`);
             emitDesktopDebug("device.connect", "device", {}, { platform: "android", stage: "success", deviceId: alreadyRunning, reused: true });
             return alreadyRunning;
         }
-        const launchedId = await launchAndWaitForAvd(parsedTarget.avdName, 60000);
-        const ready = await waitForWindowServiceReady(launchedId, 60000);
+        const launchedId = await launchAndWaitForAvd(parsedTarget.avdName, remainingTimeoutMs(deadline), { log });
+        const ready = await waitForWindowServiceReady(launchedId, remainingTimeoutMs(deadline));
         if (!ready) {
-            throw new Error("Emulator launch timed out after 60s. Check AVD health and retry.");
+            throw emulatorLaunchTimeoutError();
         }
-        console.log(`Connected to launched emulator "${parsedTarget.avdName}" as ${launchedId}`);
+        log(`Connected to launched emulator "${parsedTarget.avdName}" as ${launchedId}`);
         emitDesktopDebug("device.connect", "device", {}, {
             platform: "android",
             stage: "success",
@@ -163,7 +174,7 @@ export async function connectToDevice(deviceTargetId) {
         if (!ready) {
             throw new Error("Selected device is connected but not ready yet. Wait a moment and retry.");
         }
-        console.log(`Using selected Android device: ${targetId}`);
+        log(`Using selected Android device: ${targetId}`);
         emitDesktopDebug("device.connect", "device", {}, { platform: "android", stage: "success", deviceId: targetId, reused: true });
         return targetId;
     }

package/build/src/device/cloud/connection.js

@@ -23,7 +23,8 @@ function buildCloudCapabilities(options) {
         }
     };
 }
-export async function connectToDevice(options) {
+export async function connectToDevice(options, logOptions = {}) {
+    const log = logOptions.log || console.log;
     if (!options || typeof options !== "object") {
         throw new Error("Cloud device connection requires a provider payload.");
     }
@@ -45,7 +46,7 @@ export async function connectToDevice(options) {
         sessionName
     });
     const client = new CloudAppiumClient(platform, adapter, credentials);
-    console.log(`Creating ${adapter.displayName} session on ${deviceName} (${osVersion})...`);
+    log(`Creating ${adapter.displayName} session on ${deviceName} (${osVersion})...`);
     const session = await client.createSession(capabilities);
     activeSession = {
         client,
@@ -55,7 +56,7 @@ export async function connectToDevice(options) {
         osVersion,
         sessionId: session.sessionId
     };
-    console.log(`Connected to ${adapter.displayName} device "${deviceName}" (${session.sessionId})`);
+    log(`Connected to ${adapter.displayName} device "${deviceName}" (${session.sessionId})`);
     return session.sessionId;
 }
 export async function getDeviceInfo(sessionId) {

package/build/src/device/connection.js

@@ -12,33 +12,35 @@ let currentBackend = null;
  * @param {string} platform - Optional platform override ('android' or 'ios')
  * @returns {Promise<string>} Device ID
  */
-export async function connectToDevice(deviceNameOrOptions, platform = null) {
+export async function connectToDevice(deviceNameOrOptions, platform = null, options = {}) {
     if (deviceNameOrOptions && typeof deviceNameOrOptions === "object" && !Array.isArray(deviceNameOrOptions)) {
         const cloudOptions = deviceNameOrOptions;
         const detectedPlatform = cloudOptions.platform || detectPlatform(cloudOptions.deviceName);
         setCurrentSource(cloudOptions.source || "local");
         setCurrentPlatform(detectedPlatform);
         currentBackend = getDeviceBackend(detectedPlatform);
-        console.log(`Platform: ${detectedPlatform}`);
-        return currentBackend.connectToDevice(cloudOptions);
+        const log = options.log || console.log;
+        log(`Platform: ${detectedPlatform}`);
+        return currentBackend.connectToDevice(cloudOptions, options);
     }
     const detectedPlatform = platform || detectPlatform(deviceNameOrOptions);
     setCurrentSource("local");
     setCurrentPlatform(detectedPlatform);
     currentBackend = getDeviceBackend(detectedPlatform);
-    console.log(`Platform: ${detectedPlatform}`);
-    return currentBackend.connectToDevice(deviceNameOrOptions);
+    const log = options.log || console.log;
+    log(`Platform: ${detectedPlatform}`);
+    return currentBackend.connectToDevice(deviceNameOrOptions, options);
 }
 /**
  * Get device info (screen dimensions and scale factor)
  * @param {string} deviceId
  * @returns {Promise<object>}
  */
-export async function getDeviceInfo(deviceId) {
+export async function getDeviceInfo(deviceId, options = {}) {
     if (!currentBackend) {
         throw new Error("Not connected to a device. Call connectToDevice first.");
     }
-    return currentBackend.getDeviceInfo(deviceId);
+    return currentBackend.getDeviceInfo(deviceId, options);
 }
 /**
  * Get screenshot as base64 string

package/build/src/device/ios/appium-server.js

@@ -89,13 +89,14 @@ async function waitForAppiumReady(timeoutMs = 30000) {
  * Start Appium server if not already running
  * @returns {Promise<void>}
  */
-export async function startAppium() {
+export async function startAppium(options = {}) {
+    const log = options.log || console.log;
     if (await isAppiumRunning()) {
-        console.log("Appium server is already running");
+        log("Appium server is already running");
         return;
     }
     const appiumCommand = resolveAppiumCommand();
-    console.log(`Starting Appium server (${appiumCommand})...`);
+    log(`Starting Appium server (${appiumCommand})...`);
     try {
         appiumProcess = await spawnAppiumProcess(appiumCommand);
     }
@@ -110,7 +111,7 @@ export async function startAppium() {
     if (!ready) {
         throw new Error("Appium server failed to start within 30 seconds");
     }
-    console.log("Appium server is ready");
+    log("Appium server is ready");
 }
 /**
  * Stop the Appium server if we started it

package/build/src/device/ios/connection.js

@@ -82,12 +82,13 @@ async function findAnySimulator() {
  * @param {string} simulatorName
  * @returns {Promise<string>} UDID of the simulator
  */
-async function bootSimulator(simulatorName) {
+async function bootSimulator(simulatorName, options = {}) {
+    const log = options.log || console.log;
     const udid = await getSimulatorUDID(simulatorName);
     if (!udid) {
         throw new Error(`Simulator "${simulatorName}" not found. Run "xcrun simctl list devices" to see available simulators.`);
     }
-    console.log(`Found simulator "${simulatorName}" with UDID: ${udid}`);
+    log(`Found simulator "${simulatorName}" with UDID: ${udid}`);
     // Check if already booted
     const { stdout } = await execAsync("xcrun simctl list devices --json");
     const data = JSON.parse(stdout);
@@ -95,20 +96,20 @@ async function bootSimulator(simulatorName) {
         for (const device of runtime) {
             if (device.udid === udid) {
                 if (device.state === "Booted") {
-                    console.log(`Simulator "${simulatorName}" is already booted`);
+                    log(`Simulator "${simulatorName}" is already booted`);
                     return udid;
                 }
                 break;
             }
         }
     }
-    console.log(`Booting simulator "${simulatorName}"...`);
+    log(`Booting simulator "${simulatorName}"...`);
     await execAsync(`xcrun simctl boot ${udid}`);
     // Open Simulator app to show the device
     await execAsync("open -a Simulator");
     // Wait for boot to complete
     await waitForSimulatorBoot(udid);
-    console.log(`Simulator "${simulatorName}" is fully booted`);
+    log(`Simulator "${simulatorName}" is fully booted`);
     return udid;
 }
 /**
@@ -142,27 +143,29 @@ async function waitForSimulatorBoot(udid, timeoutMs = 60000) {
  * @param {string} simulatorName - Name of the simulator (e.g., "iPhone 16"), or null to auto-detect
  * @returns {Promise<string>} Simulator ID for use with other functions
  */
-export async function connectToDevice(simulatorName) {
+export async function connectToDevice(simulatorName, options = {}) {
+    const log = options.log || console.log;
+    const errorLog = options.errorLog || console.error;
     emitDesktopDebug("device.connect", "device", {}, { platform: "ios", stage: "start", simulatorName: simulatorName || null });
     // Setup cleanup handlers
     setupAppiumCleanup();
     // Start Appium if not running
-    await startAppium();
+    await startAppium({ log });
     // If no simulator specified, auto-detect
     if (!simulatorName) {
         const found = await findAnySimulator();
         if (!found) {
-            console.error("No iOS Simulators found. Create one with Xcode or run:");
-            console.error("  xcrun simctl create 'iPhone 16' 'com.apple.CoreSimulator.SimDeviceType.iPhone-16'");
+            errorLog("No iOS Simulators found. Create one with Xcode or run:");
+            errorLog("  xcrun simctl create 'iPhone 16' 'com.apple.CoreSimulator.SimDeviceType.iPhone-16'");
             process.exit(1);
         }
         simulatorName = found.name;
-        console.log(`No simulator specified, using: ${simulatorName}`);
+        log(`No simulator specified, using: ${simulatorName}`);
     }
     // Boot simulator
-    const udid = await bootSimulator(simulatorName);
+    const udid = await bootSimulator(simulatorName, { log });
     // Create Appium session
-    console.log("Creating Appium session...");
+    log("Creating Appium session...");
     const session = await appium.createSession({
         platformName: "iOS",
         "appium:automationName": "XCUITest",
@@ -176,7 +179,7 @@ export async function connectToDevice(simulatorName) {
         udid,
         simulatorName,
     };
-    console.log(`Connected to simulator "${simulatorName}" (${udid})`);
+    log(`Connected to simulator "${simulatorName}" (${udid})`);
     emitDesktopDebug("device.connect", "device", {}, {
         platform: "ios",
         stage: "success",
@@ -190,7 +193,8 @@ export async function connectToDevice(simulatorName) {
  * @param {string} simulatorId - The UDID returned from connectToDevice
  * @returns {Promise<object>}
  */
-export async function getDeviceInfo(simulatorId) {
+export async function getDeviceInfo(simulatorId, options = {}) {
+    const log = options.log || console.log;
     await ensureSessionAlive();
     // Get logical window size (points)
     const windowSize = await appium.getWindowSize(activeSession.sessionId);
@@ -203,7 +207,7 @@ export async function getDeviceInfo(simulatorId) {
     const pixelHeight = metadata.height;
     // Calculate the iOS device scale factor (typically 2 or 3)
     const devicePixelRatio = Math.round(pixelWidth / windowSize.width);
-    console.log(`Device pixel ratio: ${devicePixelRatio}x (${pixelWidth}x${pixelHeight} pixels, ${windowSize.width}x${windowSize.height} points)`);
+    log(`Device pixel ratio: ${devicePixelRatio}x (${pixelWidth}x${pixelHeight} pixels, ${windowSize.width}x${windowSize.height} points)`);
     // Store the pixel ratio for coordinate conversion
     activeSession.devicePixelRatio = devicePixelRatio;
     // Use pixel dimensions as the "real" resolution (like Android does)

package/build/src/device/openai.js

@@ -66,6 +66,18 @@ const navigateTool = {
         additionalProperties: false,
     },
 };
+const closeCurrentTabTool = {
+    type: "function",
+    name: "close_current_tab",
+    description: "Close the current child tab and return to the previous browser tab. Use this only when the current screen is a temporary tab or popup detour.",
+    strict: true,
+    parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+        additionalProperties: false,
+    },
+};
 const loadmillTool = {
     type: "function",
     name: "loadmill",
@@ -123,6 +135,9 @@ export function buildFunctionTools({ aimAssistMode = DEFAULT_AIM_ASSIST_MODE, to
     if (toolCapabilities.navigate) {
         tools.push(navigateTool);
     }
+    if (toolCapabilities.closeCurrentTab) {
+        tools.push(closeCurrentTabTool);
+    }
     if (toolCapabilities.loadmill) {
         tools.push(loadmillTool);
     }

package/build/src/modes/design-mode-ink.js

@@ -39,6 +39,7 @@ export class DesignModeInk {
         this.engine.toolCapabilities = {
             assert: true,
             navigate: this.session?.deviceInfo?.platform === "browser",
+            closeCurrentTab: this.session?.deviceInfo?.platform === "browser",
             loadmill: false,
             testDesignComplete: true,
         };

package/build/src/modes/design-mode.js

@@ -36,6 +36,7 @@ export class DesignMode {
         this.engine.toolCapabilities = {
             assert: true,
             navigate: this.session?.deviceInfo?.platform === "browser",
+            closeCurrentTab: this.session?.deviceInfo?.platform === "browser",
             loadmill: false,
             testDesignComplete: true,
         };

package/build/src/modes/execution-mode.js

@@ -43,6 +43,7 @@ export class ExecutionMode {
         this.engine.toolCapabilities = {
             assert: true,
             navigate: this.isBrowserSession,
+            closeCurrentTab: this.isBrowserSession,
             loadmill: true,
         };
         this.engine.baseSystemPrompt = this.initialSystemText;

package/build/src/prompts/base.js

@@ -141,6 +141,7 @@ function buildBrowserBaseSystemPrompt(deviceInfo, options = {}) {
   Browser-Specific Notes:
   - You are operating a desktop browser, not a phone UI
   - Use the \`navigate\` tool for direct URL changes when available; do not try to reach the browser address bar or fake URL entry with keyboard shortcuts
+  - Clicks or page actions that open a new tab automatically switch control to that tab; closing the current tab returns control to the previous tab
   - ESC dismisses many overlays and dialogs
   - Cookie or consent banners may block the main task and may need dismissal first
   - Vertical scrolling is the default way to discover content below the fold

package/build/src/prompts/design.js

@@ -1,7 +1,9 @@
 import { appendCustomSections, buildBaseSystemPrompt, isBrowserTarget } from "./base.js";
-export function buildDesignModePrompt(deviceInfo, customInstructions = {}) {
+import { buildAppContextSection } from "./execution.js";
+export function buildDesignModePrompt(deviceInfo, customInstructions = {}, appContextText = "") {
     const designCustomText = typeof customInstructions.designModeInstructions === "string" ? customInstructions.designModeInstructions.trim() : "";
     const basePrompt = buildBaseSystemPrompt(deviceInfo, customInstructions);
+    const appContextSection = buildAppContextSection(appContextText);
     const browserTarget = isBrowserTarget(deviceInfo);
     const prompt = `${basePrompt}
 
@@ -91,7 +93,7 @@ WRONG Example (DON'T DO THIS):
 3. etc...
 \`\`\`
 
-Remember: You are autonomous. Explore confidently. Generate simple, executable test scripts.
+Remember: You are autonomous. Explore confidently. Generate simple, executable test scripts.${appContextSection ? `\n\n${appContextSection}` : ""}
 `;
     return appendCustomSections(prompt, [
         { title: "Base Prompt Instructions", text: customInstructions.basePromptInstructions },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loadmill/droid-cua",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "description": "AI-powered Android testing agent using OpenAI's computer-use model and ADB",
   "main": "build/index.js",
   "type": "module",