@loadmill/droid-cua 2.28.0 → 2.30.0

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

@@ -0,0 +1,300 @@
+import sharp from "sharp";
+import { normalizeAutomationUrl } from "../playwright/url.js";
+import { normalizeBrowserInfoForSession } from "../normalize.js";
+import { LoadmillCloudControlPlaneClient } from "../../device/cloud/loadmill-cloud/control-plane-client.js";
+import { fetchAndDownloadArtifacts } from "../../device/cloud/loadmill-cloud/adapter.js";
+import { ARTIFACT_READY_STATUSES, TERMINAL_STATUSES } from "../../device/cloud/loadmill-cloud/run-status.js";
+import { reportCloudPhase, reportCloudProgress } from "../../device/cloud/progress.js";
+import { emitDesktopDebug } from "../../utils/desktop-debug.js";
+import { WebDriverClient } from "./client.js";
+import { createWebDriverPageFacade } from "./page-facade.js";
+import { clearActiveWebDriverSession, getActiveWebDriverSession, reportRunningOnFirstUse, setActiveWebDriverSession, } from "./session-state.js";
+export { handleModelAction } from "./actions.js";
+const DEFAULT_VIEWPORT_WIDTH = 1440;
+const DEFAULT_VIEWPORT_HEIGHT = 900;
+const LOADMILL_CLOUD_VIEWPORT = { width: DEFAULT_VIEWPORT_WIDTH, height: DEFAULT_VIEWPORT_HEIGHT };
+const VIEWPORT_METRICS_SCRIPT = "return { innerWidth: window.innerWidth, innerHeight: window.innerHeight, devicePixelRatio: window.devicePixelRatio };";
+const SESSION_PROBE_SCRIPT = "return true;";
+const TEARDOWN_STOP_BUDGET_MS = 1_500;
+async function setCloudViewport(client) {
+    await client.setWindowRect(LOADMILL_CLOUD_VIEWPORT);
+    const metrics = await client.executeScript(VIEWPORT_METRICS_SCRIPT, []);
+    const viewportWidth = Number(metrics?.innerWidth) || LOADMILL_CLOUD_VIEWPORT.width;
+    const viewportHeight = Number(metrics?.innerHeight) || LOADMILL_CLOUD_VIEWPORT.height;
+    const adjustedWindowRect = {
+        width: LOADMILL_CLOUD_VIEWPORT.width + (LOADMILL_CLOUD_VIEWPORT.width - viewportWidth),
+        height: LOADMILL_CLOUD_VIEWPORT.height + (LOADMILL_CLOUD_VIEWPORT.height - viewportHeight),
+    };
+    if (adjustedWindowRect.width !== LOADMILL_CLOUD_VIEWPORT.width ||
+        adjustedWindowRect.height !== LOADMILL_CLOUD_VIEWPORT.height) {
+        await client.setWindowRect(adjustedWindowRect);
+    }
+}
+async function attachWebDriverSession({ webdriverEndpoint, webdriverSessionId, cloud = null }) {
+    const client = new WebDriverClient({ url: webdriverEndpoint, sessionId: webdriverSessionId });
+    if (cloud) {
+        await setCloudViewport(client);
+    }
+    const windowHandle = await client.getWindowHandle();
+    const page = createWebDriverPageFacade({ client });
+    const session = {
+        sessionId: webdriverSessionId,
+        client,
+        page,
+        pageUrls: new Map(),
+        url: null,
+        cloud,
+        windowStack: [windowHandle],
+        activeWindowHandle: windowHandle,
+    };
+    setActiveWebDriverSession(session);
+    return webdriverSessionId;
+}
+async function syncActiveWindow(session) {
+    const handles = await session.client.getWindowHandles();
+    const openHandles = new Set(handles);
+    session.windowStack = session.windowStack.filter((handle) => openHandles.has(handle));
+    const knownHandles = new Set(session.windowStack);
+    const newHandles = handles.filter((handle) => !knownHandles.has(handle));
+    session.windowStack.push(...newHandles);
+    const nextHandle = newHandles.at(-1) ?? (openHandles.has(session.activeWindowHandle) ? null : session.windowStack.at(-1));
+    if (nextHandle) {
+        await session.client.switchToWindow(nextHandle);
+        session.activeWindowHandle = nextHandle;
+    }
+}
+async function probeAttachedWebDriverSession({ webdriverEndpoint, webdriverSessionId }, cloudSessionId) {
+    const probeClient = new WebDriverClient({ url: webdriverEndpoint, sessionId: webdriverSessionId });
+    try {
+        await probeClient.executeScript(SESSION_PROBE_SCRIPT, []);
+    }
+    catch (error) {
+        throw new Error(`Loadmill Cloud web session expired: session ${cloudSessionId}'s attached browser is no longer reachable — ${error.message}`);
+    }
+}
+function formatQueueMessage(state) {
+    const parts = [];
+    if (typeof state.queuePosition === "number") {
+        parts.push(`queue position ${state.queuePosition}`);
+    }
+    if (typeof state.etaSeconds === "number") {
+        parts.push(`up to ${Math.max(1, Math.round(state.etaSeconds / 60))}m`);
+    }
+    return parts.length > 0 ? parts.join(", ") : "waiting for a browser slot";
+}
+function waitForProvisionedWebDriverSession(client, sessionId, { signal } = {}) {
+    return new Promise((resolve, reject) => {
+        const watchAbort = new AbortController();
+        let lastStatus = null;
+        let settled = false;
+        const settle = (fn, value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            watchAbort.abort();
+            fn(value);
+        };
+        if (signal?.aborted) {
+            settle(reject, signal.reason ?? new Error("Provisioning cancelled."));
+            return;
+        }
+        signal?.addEventListener("abort", () => settle(reject, signal.reason ?? new Error("Provisioning cancelled.")), { once: true });
+        client
+            .watchRun(sessionId, (state) => {
+            if (!state || typeof state !== "object") {
+                return;
+            }
+            if (state.status && state.status !== lastStatus) {
+                lastStatus = state.status;
+                reportCloudPhase(state.status.toLowerCase());
+            }
+            if (state.status === "PENDING") {
+                reportCloudProgress(formatQueueMessage(state));
+            }
+            if (state.status === "PROVISIONED" && state.webdriverEndpoint) {
+                settle(resolve, {
+                    webdriverEndpoint: state.webdriverEndpoint,
+                    webdriverSessionId: state.webdriverSessionId,
+                });
+                return;
+            }
+            if (state.status === "ERROR") {
+                settle(reject, new Error(state.error?.message || "Loadmill Cloud web run failed while provisioning."));
+                return;
+            }
+            if (state.status === "CANCELLED") {
+                settle(reject, new Error("Loadmill Cloud web run was cancelled."));
+            }
+        }, { signal: watchAbort.signal })
+            .catch(() => { });
+    });
+}
+async function connectToBrowserViaLoadmillCloud({ credentials, browserFamily, browserVersion, cloudSessionId, artifacts, signal, }) {
+    const client = new LoadmillCloudControlPlaneClient({
+        bearerToken: credentials?.bearerToken,
+        baseUrl: credentials?.baseUrl,
+        pool: "web",
+    });
+    if (cloudSessionId) {
+        const state = await client.getRunState(cloudSessionId);
+        if (ARTIFACT_READY_STATUSES.has(state.status) && Array.isArray(artifacts) && artifacts.length > 0) {
+            await fetchAndDownloadArtifacts({ client, sessionId: cloudSessionId, kinds: artifacts });
+            const exitError = new Error("Loadmill Cloud artifact fetch complete.");
+            exitError.artifactsOnlyExit = true;
+            throw exitError;
+        }
+        if (TERMINAL_STATUSES.has(state.status)) {
+            throw new Error(`Loadmill Cloud web session ${cloudSessionId} is already terminal (${state.status}). ` +
+                `Fetch its recordings/logs instead with: droid-cua --target web --cloud-session-id ${cloudSessionId} --artifacts all`);
+        }
+        if (!state.webdriverEndpoint || !state.webdriverSessionId) {
+            throw new Error(`Loadmill Cloud web session ${cloudSessionId} is not yet ready to reconnect (status: ${state.status}).`);
+        }
+        await probeAttachedWebDriverSession(state, cloudSessionId);
+        if (state.status === "PROVISIONED") {
+            await client.reportStatus(cloudSessionId, "CONNECTED");
+        }
+        client.startHeartbeat(cloudSessionId);
+        try {
+            return await attachWebDriverSession({
+                webdriverEndpoint: state.webdriverEndpoint,
+                webdriverSessionId: state.webdriverSessionId,
+                cloud: { client, sessionId: cloudSessionId, runningReported: state.status === "RUNNING", artifacts },
+            });
+        }
+        catch (error) {
+            client.stopHeartbeat();
+            throw error;
+        }
+    }
+    reportCloudPhase("request browser");
+    const initState = await client.initRun({ platform: "web", deviceName: browserFamily, osVersion: browserVersion });
+    const sessionId = initState.sessionId;
+    // Server reaper kills runs that only heartbeat after CONNECTED, so start now.
+    client.startHeartbeat(sessionId);
+    try {
+        const { webdriverEndpoint, webdriverSessionId } = await waitForProvisionedWebDriverSession(client, sessionId, {
+            signal,
+        });
+        await client.reportStatus(sessionId, "CONNECTED");
+        return await attachWebDriverSession({
+            webdriverEndpoint,
+            webdriverSessionId,
+            cloud: { client, sessionId, runningReported: false, artifacts },
+        });
+    }
+    catch (error) {
+        client.stopHeartbeat();
+        await client.stopRun(sessionId, { signal: AbortSignal.timeout(TEARDOWN_STOP_BUDGET_MS) }).catch(() => { });
+        throw error;
+    }
+}
+export async function connectToBrowser(options = {}) {
+    if (options.source === "loadmill-cloud") {
+        return connectToBrowserViaLoadmillCloud(options);
+    }
+    const { url, sessionId } = options;
+    if (!url || !sessionId) {
+        throw new Error("Attaching to a WebDriver session requires a url and a sessionId.");
+    }
+    return attachWebDriverSession({ webdriverEndpoint: url, webdriverSessionId: sessionId, cloud: null });
+}
+export async function getBrowserInfo(browserSessionId) {
+    const session = getActiveWebDriverSession(browserSessionId);
+    reportRunningOnFirstUse(browserSessionId);
+    await syncActiveWindow(session);
+    const metrics = await session.client.executeScript(VIEWPORT_METRICS_SCRIPT, []);
+    const viewportWidth = Number(metrics?.innerWidth) || DEFAULT_VIEWPORT_WIDTH;
+    const viewportHeight = Number(metrics?.innerHeight) || DEFAULT_VIEWPORT_HEIGHT;
+    const devicePixelRatio = Number(metrics?.devicePixelRatio) || 1;
+    return normalizeBrowserInfoForSession({
+        viewportWidth,
+        viewportHeight,
+        scaledWidth: viewportWidth,
+        scaledHeight: viewportHeight,
+        scale: 1,
+        devicePixelRatio,
+        currentUrl: session.url,
+    });
+}
+export async function getScreenshotAsBase64(browserSessionId, browserInfo = {}) {
+    const session = getActiveWebDriverSession(browserSessionId);
+    const currentBrowserInfo = await getBrowserInfo(browserSessionId);
+    Object.assign(browserInfo, currentBrowserInfo);
+    const rawBase64 = await session.client.getScreenshot();
+    let buffer = Buffer.from(rawBase64, "base64");
+    if (currentBrowserInfo.scaledWidth && currentBrowserInfo.scaledHeight) {
+        buffer = await sharp(buffer)
+            .resize({
+            width: currentBrowserInfo.scaledWidth,
+            height: currentBrowserInfo.scaledHeight,
+            fit: "fill",
+        })
+            .png()
+            .toBuffer();
+    }
+    return buffer.toString("base64");
+}
+export async function navigateToUrl(browserSessionId, url) {
+    const session = getActiveWebDriverSession(browserSessionId);
+    reportRunningOnFirstUse(browserSessionId);
+    const normalizedUrl = normalizeAutomationUrl(url);
+    await session.page.goto(normalizedUrl, { waitUntil: "load" });
+    session.pageUrls.set(session.page, normalizedUrl);
+    session.url = normalizedUrl;
+    return normalizedUrl;
+}
+export async function closeCurrentTab(browserSessionId) {
+    const session = getActiveWebDriverSession(browserSessionId);
+    await syncActiveWindow(session);
+    if (session.windowStack.length <= 1) {
+        return {
+            closed: false,
+            restoredUrl: null,
+            message: "The primary browser tab cannot be closed.",
+        };
+    }
+    await session.client.closeWindow();
+    session.windowStack.pop();
+    session.activeWindowHandle = session.windowStack.at(-1);
+    await session.client.switchToWindow(session.activeWindowHandle);
+    const restoredUrl = await session.page.url();
+    session.url = restoredUrl;
+    const message = restoredUrl
+        ? `Closed current tab. Returned to ${restoredUrl}.`
+        : "Closed current tab. Returned to the previous browser tab.";
+    emitDesktopDebug("browser.tab.close_current", "device", { browserSessionId }, {
+        platform: "browser",
+        closed: true,
+        restoredUrl,
+        stackDepth: session.windowStack.length,
+    });
+    return {
+        closed: true,
+        restoredUrl,
+        message,
+    };
+}
+export async function disconnect() {
+    let session = null;
+    try {
+        session = getActiveWebDriverSession();
+    }
+    catch {
+        session = null;
+    }
+    clearActiveWebDriverSession();
+    if (session?.cloud) {
+        const { client, sessionId, artifacts } = session.cloud;
+        try {
+            await client.stopRun(sessionId);
+            if (Array.isArray(artifacts) && artifacts.length > 0) {
+                await fetchAndDownloadArtifacts({ client, sessionId, kinds: artifacts });
+            }
+        }
+        finally {
+            client.stopHeartbeat();
+        }
+    }
+}

package/build/src/browser/webdriver/page-facade.js

@@ -0,0 +1,123 @@
+const W3C_KEY_CODES = {
+    Backspace: "",
+    Tab: "",
+    Enter: "",
+    Shift: "",
+    Control: "",
+    Alt: "",
+    Escape: "",
+    Space: "",
+    PageUp: "",
+    PageDown: "",
+    End: "",
+    Home: "",
+    ArrowLeft: "",
+    ArrowUp: "",
+    ArrowRight: "",
+    ArrowDown: "",
+    Delete: "",
+    Meta: "",
+};
+const SCROLL_BY_SCRIPT = "window.scrollBy(arguments[0], arguments[1]);";
+function keyCodeFor(name) {
+    return W3C_KEY_CODES[name] ?? name;
+}
+function pointerSource(steps) {
+    return [{ type: "pointer", id: "mouse", parameters: { pointerType: "mouse" }, actions: steps }];
+}
+function keySource(steps) {
+    return [{ type: "key", id: "keyboard", actions: steps }];
+}
+/**
+ * A Playwright-`page`-shaped facade over a `WebDriverClient`, exposing only
+ * the surface the shared gesture dispatch drives and encoding every gesture
+ * to its exact W3C JSON body.
+ *
+ * @param {{ client: import("./client.js").WebDriverClient, scrollMode?: "wheel"|"script" }} options
+ */
+export function createWebDriverPageFacade({ client, scrollMode = "wheel" }) {
+    return {
+        mouse: {
+            async click(x, y) {
+                await client.performActions(pointerSource([
+                    { type: "pointerMove", duration: 0, x, y },
+                    { type: "pointerDown", button: 0 },
+                    { type: "pause", duration: 100 },
+                    { type: "pointerUp", button: 0 },
+                ]));
+            },
+            async dblclick(x, y) {
+                await client.performActions(pointerSource([
+                    { type: "pointerMove", duration: 0, x, y },
+                    { type: "pointerDown", button: 0 },
+                    { type: "pointerUp", button: 0 },
+                    { type: "pointerDown", button: 0 },
+                    { type: "pointerUp", button: 0 },
+                ]));
+            },
+            async move(x, y) {
+                await client.performActions(pointerSource([{ type: "pointerMove", duration: 0, x, y }]));
+            },
+            async down() {
+                await client.performActions(pointerSource([{ type: "pointerDown", button: 0 }]));
+            },
+            async up() {
+                await client.performActions(pointerSource([{ type: "pointerUp", button: 0 }]));
+            },
+            async wheel(deltaX, deltaY) {
+                if (scrollMode === "script") {
+                    await client.executeScript(SCROLL_BY_SCRIPT, [deltaX, deltaY]);
+                    return;
+                }
+                await client.performActions([
+                    {
+                        type: "wheel",
+                        id: "wheel",
+                        actions: [{ type: "scroll", x: 0, y: 0, deltaX, deltaY, duration: 0 }],
+                    },
+                ]);
+            },
+        },
+        keyboard: {
+            async down(key) {
+                await client.performActions(keySource([{ type: "keyDown", value: key }]));
+            },
+            async up(key) {
+                await client.performActions(keySource([{ type: "keyUp", value: key }]));
+            },
+            async press(shortcut) {
+                const codes = String(shortcut).split("+").map(keyCodeFor);
+                const downs = codes.map((value) => ({ type: "keyDown", value }));
+                const ups = [...codes].reverse().map((value) => ({ type: "keyUp", value }));
+                await client.performActions(keySource([...downs, ...ups]));
+            },
+            async type(text) {
+                const steps = [];
+                for (const char of String(text)) {
+                    steps.push({ type: "keyDown", value: char });
+                    steps.push({ type: "keyUp", value: char });
+                }
+                await client.performActions(keySource(steps));
+            },
+        },
+        async goto(url) {
+            await client.navigateTo(url);
+        },
+        async goBack() {
+            await client.goBack();
+        },
+        async goForward() {
+            await client.goForward();
+        },
+        async url() {
+            return await client.executeScript("return window.location.href;", []);
+        },
+        async screenshot() {
+            const base64 = await client.getScreenshot();
+            return Buffer.from(base64, "base64");
+        },
+        async waitForTimeout(ms) {
+            await new Promise((resolve) => setTimeout(resolve, ms));
+        },
+    };
+}

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

@@ -0,0 +1,35 @@
+let activeSession = null;
+export function setActiveWebDriverSession(session) {
+    activeSession = session;
+}
+export function clearActiveWebDriverSession() {
+    activeSession = null;
+}
+export function getActiveWebDriverSession(browserSessionId = null) {
+    if (!activeSession) {
+        throw new Error("Not attached to a WebDriver session. Call connectToBrowser first.");
+    }
+    if (browserSessionId && activeSession.sessionId !== browserSessionId) {
+        throw new Error("Requested WebDriver session is no longer active.");
+    }
+    return activeSession;
+}
+export function getActiveWebDriverPage(browserSessionId = null) {
+    return getActiveWebDriverSession(browserSessionId).page;
+}
+export function reportRunningOnFirstUse(browserSessionId = null) {
+    let session = null;
+    try {
+        session = getActiveWebDriverSession(browserSessionId);
+    }
+    catch {
+        return;
+    }
+    if (!session.cloud || session.cloud.runningReported) {
+        return;
+    }
+    session.cloud.runningReported = true;
+    session.cloud.client.reportStatus(session.cloud.sessionId, "RUNNING").catch((error) => {
+        console.error(`[loadmill-cloud] failed to report RUNNING status: ${error.message}`);
+    });
+}

package/build/src/cli/headless-execution-config.js

@@ -224,7 +224,7 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
         llmProviderMode: fileConfig?.llmProviderMode || readEnvDefaultLlmProviderMode(),
         cuaModel: fileConfig?.cuaModel || readEnvDefaultCuaModel(),
         aimAssistMode: fileConfig?.aimAssistMode || DEFAULT_AIM_ASSIST_MODE,
-        explainMode: fileConfig?.explainMode ?? false,
+        explainMode: fileConfig?.explainMode ?? true,
         promptCustomizations,
         appContextEnabled: fileConfig?.appContextEnabled ?? true,
         appContextPath: fileConfig?.appContextPath || null,

package/build/src/cli/headless-runner.js

@@ -12,7 +12,9 @@ import { reportDroidCuaCiTestRunCompleted } from "../integrations/segment/droid-
 import { printCliOutput } from "../utils/console-output.js";
 import { emitDesktopDebug } from "../utils/desktop-debug.js";
 import { loadHeadlessInstructions } from "./headless-instructions.js";
+import { formatHeadlessTestSourceLabel } from "./headless-test-source-label.js";
 import { buildCliRunReportModel, createCapturingAddOutput, createCliAggregateRunReport, createCliRunReport, renderCliCloudReport, writeCliRunReportArtifact, } from "./headless-report.js";
+import { createRefuseReconnectConnectToBrowser } from "../desktop-shared/connection-predicates.js";
 function sanitizePathSegment(value) {
     return String(value || "test")
         .replace(/\.dcua$/i, "")
@@ -80,7 +82,10 @@ function emitCliAppContextDebug(runId, appContext, appContextText) {
         });
     }
 }
-function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionPrompt, screenshotRecorder, recordScreenshots, screenshotDir, isBrowserTarget, isCloudTarget, onCuaResponse = null, secrets = null }) {
+export function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionPrompt, screenshotRecorder, recordScreenshots, screenshotDir, isBrowserTarget, isCloudTarget, runTarget = null, onCuaResponse = null, secrets = null }) {
+    const resolvedRunTarget = runTarget ?? { isBrowserTarget, isCloudTarget };
+    const isBrowserRunTarget = Boolean(resolvedRunTarget.isBrowserTarget);
+    const isCloudRunTarget = Boolean(resolvedRunTarget.isCloudTarget);
     const sendCUARequest = async (requestArgs) => {
         const response = await runtimeContext.openAi.sendCUARequest({
             ...requestArgs,
@@ -94,8 +99,8 @@ function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionP
     const executionEngineOptions = {
         toolCapabilities: {
             assert: true,
-            navigate: isBrowserTarget,
-            closeKeyboard: !isBrowserTarget,
+            navigate: isBrowserRunTarget,
+            closeKeyboard: !isBrowserRunTarget,
             loadmill: true,
         },
         secretsByKey: secrets?.secretsByKey || {},
@@ -119,19 +124,24 @@ function buildHeadlessEngineOptions({ runtimeContext, headlessConfig, executionP
             reviseTestScript: runtimeContext.openAi.reviseTestScript,
             ...executionEngineOptions,
         };
-    if (isBrowserTarget) {
+    if (isBrowserRunTarget) {
         engineOptions.getScreenshotAsBase64 = (browserSessionId, browserInfo) => getBrowserScreenshotAsBase64(browserSessionId, browserInfo);
         engineOptions.handleModelAction = (browserSessionId, action, scale, actionContext) => handleBrowserModelAction(browserSessionId, action, scale, actionContext);
         engineOptions.getCurrentPlatform = getBrowserCurrentPlatform;
     }
-    else if (isCloudTarget) {
-        engineOptions.connectToDevice = async () => {
-            throw new Error("Cloud session disconnected; automatic CLI reconnect is not supported yet.");
-        };
+    if (isCloudRunTarget) {
+        if (isBrowserRunTarget) {
+            engineOptions.connectToBrowser = createRefuseReconnectConnectToBrowser();
+        }
+        else {
+            engineOptions.connectToDevice = async () => {
+                throw new Error("Cloud session disconnected; automatic CLI reconnect is not supported yet.");
+            };
+        }
     }
     return engineOptions;
 }
-async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, testDataContext = "", runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isCloudTarget, secrets = null, report = null, isBatchRun = false, reportToLoadmill = true, cloudUploadSession = null, uploadManager = droidReportUploadManager, }) {
+async function runHeadlessTest({ runId, testPath, testName, instructions, session, deviceInfo, headlessConfig, appContext, testDataContext = "", runtimeContext, headlessDebug, recordScreenshots, screenshotDir, isBrowserTarget, isCloudTarget, runTarget = null, secrets = null, report = null, isBatchRun = false, reportToLoadmill = true, cloudUploadSession = null, uploadManager = droidReportUploadManager, }) {
     let executionMode = null;
     let loadmillSessionUser = null;
     let runUsageTotals = setDroidCuaRunUsageModel(createDroidCuaRunUsageTotals(), runtimeContext.config.cuaModel);
@@ -181,7 +191,7 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
         if (currentLogFilePath) {
             console.log(`Debug logging enabled: ${currentLogFilePath}`);
         }
-        console.log(`\nRunning test from: ${testPath}\n`);
+        console.log(`\nRunning test from: ${formatHeadlessTestSourceLabel(testPath)}\n`);
         const appContextText = appContext.text;
         emitCliAppContextDebug(runId, appContext, appContextText);
         session.updateResponseId(undefined);
@@ -208,6 +218,7 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
             screenshotDir,
             isBrowserTarget,
             isCloudTarget,
+            runTarget,
             onCuaResponse: (response) => {
                 runUsageTotals = addOpenAiResponseToDroidCuaRunUsage(runUsageTotals, response);
             },
@@ -414,7 +425,8 @@ async function runHeadlessTest({ runId, testPath, testName, instructions, sessio
         throw error;
     }
 }
-export async function runHeadlessInstructionRuns({ runs, instructionsTarget, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, secrets = null, recordScreenshots, screenshotDir, isBrowserTarget, isCloudTarget, report = null, runHeadlessTestImpl = runHeadlessTest, uploadManager = droidReportUploadManager, }) {
+export async function runHeadlessInstructionRuns({ runs, instructionsTarget, session, deviceInfo, headlessConfig, appContext, runtimeContext, headlessDebug, secrets = null, recordScreenshots, screenshotDir, isBrowserTarget, isCloudTarget, runTarget = null, report = null, runHeadlessTestImpl = runHeadlessTest, uploadManager = droidReportUploadManager, }) {
+    const resolvedRunTarget = runTarget ?? { isBrowserTarget, isCloudTarget };
     const isBatchRun = instructionsTarget?.type === "directory" || instructionsTarget?.type === "scenario";
     const cloudReportEnabled = report?.cloudEnabled !== false &&
         Boolean(runtimeContext.loadmillClient?.getApiToken?.());
@@ -468,8 +480,9 @@ export async function runHeadlessInstructionRuns({ runs, instructionsTarget, ses
                 secrets,
                 recordScreenshots,
                 screenshotDir: testScreenshotDir,
-                isBrowserTarget,
-                isCloudTarget,
+                isBrowserTarget: resolvedRunTarget.isBrowserTarget,
+                isCloudTarget: resolvedRunTarget.isCloudTarget,
+                runTarget: resolvedRunTarget,
                 report,
                 isBatchRun,
                 reportToLoadmill: !isBatchRun,