@loadmill/droid-cua 2.29.0 → 2.30.0

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,

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

@@ -1,3 +1,4 @@
+import { CLOUD_BROWSER_FAMILIES, CLOUD_BROWSER_VERSION_ALIASES, LOCAL_BROWSER_FAMILIES, } from "../browser/cloud-browser-catalog.js";
 function normalizeTarget(value) {
     if (value == null || value === "") {
         return "mobile";
@@ -24,18 +25,31 @@ function normalizeSessionMode(value) {
     }
     throw new Error("--session-mode must be one of: persistent, fresh.");
 }
-function normalizeBrowser(value) {
+function normalizeBrowser(value, allowedFamilies) {
     if (value == null || value === "") {
         return "chrome";
     }
     if (typeof value !== "string") {
-        throw new Error("--browser must be one of: chrome, edge.");
+        throw new Error(`--browser must be one of: ${allowedFamilies.join(", ")}.`);
     }
     const normalized = value.trim().toLowerCase();
-    if (normalized === "chrome" || normalized === "edge") {
+    if (allowedFamilies.includes(normalized)) {
         return normalized;
     }
-    throw new Error("--browser must be one of: chrome, edge.");
+    throw new Error(`--browser must be one of: ${allowedFamilies.join(", ")}.`);
+}
+function normalizeCloudBrowserVersion(value) {
+    if (value == null || value === "") {
+        return "latest";
+    }
+    if (typeof value !== "string") {
+        throw new Error(`--browser-version must be one of: ${CLOUD_BROWSER_VERSION_ALIASES.join(", ")}.`);
+    }
+    const normalized = value.trim().toLowerCase();
+    if (CLOUD_BROWSER_VERSION_ALIASES.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`--browser-version must be one of: ${CLOUD_BROWSER_VERSION_ALIASES.join(", ")}.`);
 }
 const CLOUD_SOURCE_DISPLAY_NAMES = {
     lambdatest: "LambdaTest",
@@ -80,25 +94,48 @@ function readNonEmptyCliValue(value) {
     }
     return null;
 }
-const ARTIFACT_KINDS = ["video", "deviceLog", "appiumLog"];
-function normalizeArtifactKinds(value) {
+export const MOBILE_ARTIFACT_KINDS = ["video", "deviceLog", "appiumLog"];
+export const WEB_ARTIFACT_KINDS = ["video", "seleniumLog"];
+const UNRESOLVED_POOL_ARTIFACT_KINDS = [...MOBILE_ARTIFACT_KINDS, "seleniumLog"];
+const ARTIFACT_KINDS_BY_POOL = {
+    mobile: MOBILE_ARTIFACT_KINDS,
+    web: WEB_ARTIFACT_KINDS,
+};
+export function artifactKindsForPool(pool) {
+    const kinds = ARTIFACT_KINDS_BY_POOL[pool];
+    if (!kinds) {
+        throw new Error(`Unknown Loadmill Cloud pool: ${pool}. Expected "mobile" or "web".`);
+    }
+    return [...kinds];
+}
+export function scopeArtifactKindsToPool(kinds, pool) {
+    const allowed = artifactKindsForPool(pool);
+    return kinds.filter((kind) => allowed.includes(kind));
+}
+function allowedArtifactKindsForTarget(target, poolKnown) {
+    if (!poolKnown) {
+        return UNRESOLVED_POOL_ARTIFACT_KINDS;
+    }
+    return target === "web" ? WEB_ARTIFACT_KINDS : MOBILE_ARTIFACT_KINDS;
+}
+function normalizeArtifactKinds(value, allowedKinds) {
     if (value == null || value === "") {
         return null;
     }
     if (typeof value !== "string") {
-        throw new Error(`--artifacts must be a comma-separated list of: ${ARTIFACT_KINDS.join(", ")}, or all.`);
+        throw new Error(`--artifacts must be a comma-separated list of: ${allowedKinds.join(", ")}, or all.`);
     }
     const raw = value.trim();
     if (!raw) {
         return null;
     }
     if (raw.toLowerCase() === "all") {
-        return [...ARTIFACT_KINDS];
+        return [...allowedKinds];
     }
     const kinds = [...new Set(raw.split(",").map((kind) => kind.trim()).filter(Boolean))];
-    const invalid = kinds.filter((kind) => !ARTIFACT_KINDS.includes(kind));
+    const invalid = kinds.filter((kind) => !allowedKinds.includes(kind));
     if (invalid.length > 0) {
-        throw new Error(`--artifacts has invalid kind(s): ${invalid.join(", ")}. Must be one of: ${ARTIFACT_KINDS.join(", ")}, or all.`);
+        throw new Error(`--artifacts has invalid kind(s): ${invalid.join(", ")}. Must be one of: ${allowedKinds.join(", ")}, or all.`);
     }
     return kinds;
 }
@@ -144,9 +181,10 @@ function normalizeCloudAppPath(value, platform, deviceSource) {
 export function shouldWaitForLoadmillCloudCompletion(targetConfig) {
     return Array.isArray(targetConfig?.artifacts) && targetConfig.artifacts.length > 0;
 }
+const MOBILE_ONLY_CLOUD_SOURCES = new Set(["lambdatest", "aws-device-farm"]);
 export function resolveHeadlessTarget(args = {}) {
     const target = normalizeTarget(args.target);
-    const sessionMode = normalizeSessionMode(args["session-mode"]);
+    const targetGiven = hasNonEmptyString(args.target);
     const avdName = hasNonEmptyString(args.avd) ? args.avd.trim() : null;
     const platform = normalizeMobilePlatform(args.platform, "--platform");
     // The mtc_ prefix on --cloud-session-id is loadmill-cloud's; when no
@@ -164,14 +202,44 @@ export function resolveHeadlessTarget(args = {}) {
         if (avdName || platform) {
             throw new Error("--avd and --platform cannot be used with --target web.");
         }
-        if (deviceSource !== "local") {
-            throw new Error("--device-source can only be used with --target mobile.");
+        if (MOBILE_ONLY_CLOUD_SOURCES.has(deviceSource)) {
+            throw new Error(`--device-source ${deviceSource} can only be used with --target mobile.`);
+        }
+        if (hasNonEmptyString(args["device-name"])) {
+            throw new Error("--device-name cannot be used with --target web.");
+        }
+        if (readNonEmptyCliValue(args["os-version"]) != null) {
+            throw new Error("--os-version cannot be used with --target web.");
+        }
+        if (hasNonEmptyString(args.app)) {
+            throw new Error("--app cannot be used with --target web.");
+        }
+        if (deviceSource === "loadmill-cloud") {
+            if (args["session-mode"] != null) {
+                throw new Error("--session-mode can only be used with --device-source local.");
+            }
+            return {
+                target,
+                sessionMode: null,
+                browserFamily: normalizeBrowser(args.browser, CLOUD_BROWSER_FAMILIES),
+                browserVersion: normalizeCloudBrowserVersion(args["browser-version"]),
+                deviceSource: "loadmill-cloud",
+                avdName: null,
+                platform: null,
+                deviceName: null,
+                osVersion: null,
+                appPath: null,
+                cloudSessionId: readNonEmptyCliValue(args["cloud-session-id"]),
+                artifacts: normalizeArtifactKinds(args.artifacts, WEB_ARTIFACT_KINDS),
+                listDevices: false,
+            };
         }
         assertNoCloudFlags(args);
         return {
             target,
-            sessionMode,
-            browserFamily: normalizeBrowser(args.browser),
+            sessionMode: normalizeSessionMode(args["session-mode"]),
+            browserFamily: normalizeBrowser(args.browser, LOCAL_BROWSER_FAMILIES),
+            browserVersion: null,
             deviceSource: "local",
             avdName: null,
             platform: null,
@@ -195,6 +263,7 @@ export function resolveHeadlessTarget(args = {}) {
             target,
             sessionMode: null,
             browserFamily: null,
+            browserVersion: null,
             deviceSource,
             avdName: null,
             platform: null,
@@ -215,7 +284,7 @@ export function resolveHeadlessTarget(args = {}) {
         const cloudSessionId = readNonEmptyCliValue(args["cloud-session-id"]);
         const isReconnect = deviceSource === "loadmill-cloud" && Boolean(cloudSessionId);
         const appPath = normalizeCloudAppPath(args.app, platform, deviceSource);
-        const artifacts = normalizeArtifactKinds(args.artifacts);
+        const artifacts = normalizeArtifactKinds(args.artifacts, allowedArtifactKindsForTarget(target, targetGiven || !isReconnect));
         if (artifacts && deviceSource !== "loadmill-cloud") {
             throw new Error("--artifacts can only be used with --device-source loadmill-cloud.");
         }
@@ -241,6 +310,7 @@ export function resolveHeadlessTarget(args = {}) {
             target,
             sessionMode: null,
             browserFamily: null,
+            browserVersion: null,
             deviceSource,
             avdName: null,
             platform,
@@ -256,6 +326,7 @@ export function resolveHeadlessTarget(args = {}) {
         target,
         sessionMode: null,
         browserFamily: null,
+        browserVersion: null,
         deviceSource,
         avdName,
         platform,

package/build/src/cli/headless-test-source-label.js

@@ -0,0 +1,4 @@
+const INLINE_SOURCE_PATTERN = /^\/dev\/(fd\/\d+|stdin)$/;
+export function formatHeadlessTestSourceLabel(sourcePath) {
+    return INLINE_SOURCE_PATTERN.test(sourcePath) ? "(inline instructions)" : sourcePath;
+}

package/build/src/cli/loadmill-cloud-device-connect-summary.js

@@ -0,0 +1,6 @@
+export function buildLoadmillCloudDeviceConnectSummaryLines({ deviceInfo }) {
+    return [
+        `Using real resolution: ${deviceInfo.device_width}x${deviceInfo.device_height}`,
+        `Model sees resolution: ${deviceInfo.scaled_width}x${deviceInfo.scaled_height}`,
+    ];
+}

package/build/src/cli/loadmill-cloud-session.js

@@ -0,0 +1,26 @@
+export async function withLoadmillCloudSession({ credentials, connect, teardown, run = null }) {
+    const targetId = await connect(credentials);
+    if (typeof run !== "function") {
+        return targetId;
+    }
+    try {
+        return await run(targetId);
+    }
+    finally {
+        await teardown();
+    }
+}
+export function createBrowserSessionTeardown({ disconnect, releaseSession }) {
+    return async () => {
+        try {
+            await disconnect();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`[loadmill-cloud] browser disconnect failed: ${message}`);
+        }
+        finally {
+            await releaseSession();
+        }
+    };
+}

package/build/src/core/context-optimization.js

@@ -1,5 +1,5 @@
 export const DEFAULT_CONTEXT_OPTIMIZATION_ENABLED = true;
-export const DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD = 30000;
+export const DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD = 60000;
 export const MIN_CONTEXT_OPTIMIZATION_THRESHOLD = 10000;
 export const MAX_CONTEXT_OPTIMIZATION_THRESHOLD = 900000;
 export const CONTEXT_OPTIMIZATION_ENABLED_ENV = "DROID_CUA_CONTEXT_OPTIMIZATION_ENABLED";

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

@@ -503,6 +503,15 @@ export class ExecutionEngine {
     }
     emitResponseOutputItems(items, addOutput, eventMeta, options = {}) {
         for (const item of items) {
+            if (item.type === "compaction") {
+                addOutput({
+                    type: "info",
+                    text: "Optimized context",
+                    eventType: "system_message",
+                    ...eventMeta({ payload: { event: "context.optimized" } }),
+                });
+                continue;
+            }
             if (item.type === "reasoning") {
                 for (const entry of item.summary) {
                     if (entry.type !== "summary_text")

package/build/src/core/runtime-config.js

@@ -123,7 +123,7 @@ export function resolveRuntimeCredentials({ openAiApiKey = null, loadmillApiToke
         loadmillBaseUrl: normalizeLoadmillSiteBaseUrl(loadmillBaseUrl),
     };
 }
-export function resolveRuntimeConfig({ llmProviderMode = null, cuaModel = null, explainMode = false, stepDelayMs = undefined, contextOptimizationEnabled = undefined, contextOptimizationThreshold = undefined, promptCustomizations = null, appContext = null, } = {}) {
+export function resolveRuntimeConfig({ llmProviderMode = null, cuaModel = null, explainMode = true, stepDelayMs = undefined, contextOptimizationEnabled = undefined, contextOptimizationThreshold = undefined, promptCustomizations = null, appContext = null, } = {}) {
     const normalizedCuaModel = typeof cuaModel === "string" && LOADMILL_MODEL_ALIAS_SET.has(cuaModel)
         ? cuaModel
         : resolveCuaModel(cuaModel);
@@ -133,7 +133,7 @@ export function resolveRuntimeConfig({ llmProviderMode = null, cuaModel = null,
             ? "loadmill"
             : normalizedProviderMode,
         cuaModel: normalizedCuaModel,
-        explainMode: explainMode === true,
+        explainMode: explainMode !== false,
         stepDelayMs: normalizeStepDelayMs(Number(stepDelayMs)),
         contextOptimizationEnabled: normalizeContextOptimizationEnabled(contextOptimizationEnabled),
         contextOptimizationThreshold: normalizeContextOptimizationThreshold(contextOptimizationThreshold),

package/build/src/desktop-shared/connection-predicates.js

@@ -0,0 +1,52 @@
+const CLOUD_CONNECTION_SOURCES = new Set(["browserstack", "lambdatest", "aws-device-farm", "loadmill-cloud"]);
+/**
+ * True when a desktop connection needs the cloud-session lifecycle
+ * (provisioning, heartbeat, release) regardless of whether it targets a
+ * device or a browser.
+ *
+ * @param {{ source?: string | null }} connection
+ * @returns {boolean}
+ */
+export function needsCloudSessionManagement(connection) {
+    return CLOUD_CONNECTION_SOURCES.has(connection?.source);
+}
+/**
+ * True when a desktop connection should route through the browser engine
+ * hooks (screenshot/action/platform) instead of the device ones.
+ *
+ * @param {{ platform?: string | null }} connection
+ * @returns {boolean}
+ */
+export function usesBrowserEngineHooks(connection) {
+    return connection?.platform === "browser";
+}
+/**
+ * True when a desktop connection needs the Android tool-environment
+ * refresh, which only applies to Android device connections.
+ *
+ * @param {{ platform?: string | null }} connection
+ * @returns {boolean}
+ */
+export function needsAndroidToolEnvRefresh(connection) {
+    return connection?.platform === "android";
+}
+/**
+ * The status/outcome pair a desktop provisioning failure must report so the
+ * remote Loadmill classification and the local JUnit history agree.
+ *
+ * @returns {{ status: "error", outcome: "error" }}
+ */
+export function resolveProvisioningFailureReporting() {
+    return { status: "error", outcome: "error" };
+}
+/**
+ * Builds a `connectToBrowser` engine hook that refuses to relaunch a
+ * browser mid-run instead of silently starting a local one.
+ *
+ * @returns {() => Promise<never>}
+ */
+export function createRefuseReconnectConnectToBrowser() {
+    return async () => {
+        throw new Error("Cloud session disconnected; automatic CLI reconnect is not supported yet.");
+    };
+}