@loadmill/droid-cua 2.6.0 → 2.8.0

package/build/src/commands/help.js

@@ -10,20 +10,26 @@
  */
 export async function handleHelp(args, session, context) {
     const addOutput = context?.addOutput || ((item) => console.log(item.text || item));
-    addOutput({ type: 'system', text: 'droid-cua - AI-powered mobile device testing CLI' });
+    addOutput({ type: 'system', text: 'droid-cua - AI-powered mobile and web testing CLI' });
     addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Usage:' });
     addOutput({ type: 'info', text: '  droid-cua --avd <device-name> [options]' });
+    addOutput({ type: 'info', text: '  droid-cua --target web --url <starting-url> --instructions <file> [options]' });
     addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Options:' });
+    addOutput({ type: 'info', text: '  --target <kind>        Target kind: mobile (default) or web' });
     addOutput({ type: 'info', text: '  --avd <name>           Device name (Android device ID/serial or iOS Simulator)' });
     addOutput({ type: 'info', text: '  --platform <platform>  Force platform: android or ios' });
     addOutput({ type: 'info', text: '  --instructions <file>  Run test file in headless mode' });
+    addOutput({ type: 'info', text: '  --url <value>          Required starting URL for --target web headless runs' });
+    addOutput({ type: 'info', text: '  --session-mode <mode>  Browser session mode for web runs: persistent or fresh' });
     addOutput({ type: 'info', text: '  --config <file>        Headless execution JSON config for prompt parity' });
-    addOutput({ type: 'info', text: '  --cua-model <model>    Headless CUA model override: gpt-5.4 or computer-use-preview' });
+    addOutput({ type: 'info', text: '  --cua-model <model>    Headless CUA model override: gpt-5.4, gpt-5.4-mini, or computer-use-preview' });
     addOutput({ type: 'info', text: '  --context <file>       Optional app context file used to brief execution runs' });
     addOutput({ type: 'info', text: '  --app-context-budget   Headless app context token budget override' });
     addOutput({ type: 'info', text: '  --no-context           Disable app context for headless execution' });
+    addOutput({ type: 'info', text: '  --context-optimization-threshold <tokens> Headless Context Optimization compaction threshold' });
+    addOutput({ type: 'info', text: '  --no-context-optimization Disable Context Optimization for headless execution' });
     addOutput({ type: 'info', text: '  --base-prompt <text>   Headless base prompt customization text' });
     addOutput({ type: 'info', text: '  --execution-prompt <text> Headless execution prompt customization text' });
     addOutput({ type: 'info', text: '  --base-prompt-file     Headless base prompt customization file' });
@@ -50,6 +56,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: 'Platform Support:' });
     addOutput({ type: 'info', text: '  Android: Uses ADB to communicate with Android devices (physical or emulator)' });
     addOutput({ type: 'info', text: '  iOS:     Uses Appium + XCUITest for iOS Simulator automation' });
+    addOutput({ type: 'info', text: '  Web:     Uses Playwright with installed Google Chrome or Microsoft Edge for browser execution' });
     addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Platform Detection:' });
     addOutput({ type: 'info', text: '  - Use --platform flag to force a specific platform' });
@@ -69,6 +76,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  droid-cua --avd "iPhone 16"             (iOS Simulator, auto-detected)' });
     addOutput({ type: 'info', text: '  droid-cua --platform ios --avd MySim    (Force iOS platform)' });
     addOutput({ type: 'info', text: '  droid-cua --instructions tests/login.dcua --context app/context.md' });
+    addOutput({ type: 'info', text: '  droid-cua --target web --url docs.example.com --instructions tests/search.dcua' });
     addOutput({ type: 'info', text: '  /create login-test                      (design a new test)' });
     addOutput({ type: 'info', text: '  /list                                   (see all tests)' });
     addOutput({ type: 'info', text: '  /view login-test                        (view test contents)' });

package/build/src/core/capture-sources.js

@@ -0,0 +1,76 @@
+// Single source of truth for screenshot/click-annotation provenance. Producers
+// stamp `captureSource` on every event; consumers (renderer log filter, main
+// result-artifact router, debug recorder) read it through classifyCaptureSource.
+//
+// classifyCaptureSource returns three orthogonal axes — each consumer reads only
+// what it needs:
+//   - mediaKind: how the renderer should display the event ('hidden-debug'
+//     hides it from the timeline, 'screenshot' / 'click-annotation' put it in
+//     the gallery, null leaves it as plain text).
+//   - persistsToResults: whether the main process copies the artifact into the
+//     run's user-visible result directory (vs. debug-only).
+//   - visibility: whether the event represents user-facing action ('user'),
+//     internal preview/debug noise ('debug'), or has no associated media
+//     ('none'). Distinct from mediaKind because INSTRUCTION_INPUT and
+//     DESIGN_INPUT are real user inputs but don't appear in the gallery.
+export const CAPTURE_SOURCES = Object.freeze({
+    PREVIEW_CLICK: "preview-click",
+    ACTION_CLICK_ANNOTATION: "action-click-annotation",
+    CALL_OUTPUT_POST_ACTION: "call-output-post-action",
+    CALL_OUTPUT_EXPLICIT_ACTION: "call-output-explicit-action",
+    INSTRUCTION_INPUT: "instruction-input",
+    INSTRUCTION_INPUT_ASSERTION: "instruction-input-assertion",
+    DESIGN_INPUT: "design-input",
+});
+const HIDDEN_DEBUG_MEDIA_KINDS = new Set([
+    CAPTURE_SOURCES.PREVIEW_CLICK,
+]);
+const CLICK_ANNOTATION_MEDIA_KINDS = new Set([
+    CAPTURE_SOURCES.ACTION_CLICK_ANNOTATION,
+]);
+const SCREENSHOT_MEDIA_KINDS = new Set([
+    CAPTURE_SOURCES.CALL_OUTPUT_POST_ACTION,
+    CAPTURE_SOURCES.CALL_OUTPUT_EXPLICIT_ACTION,
+    CAPTURE_SOURCES.INSTRUCTION_INPUT_ASSERTION,
+]);
+const USER_VISIBLE_RESULT_CAPTURE_SOURCES = new Set([
+    CAPTURE_SOURCES.CALL_OUTPUT_POST_ACTION,
+    CAPTURE_SOURCES.CALL_OUTPUT_EXPLICIT_ACTION,
+    CAPTURE_SOURCES.INSTRUCTION_INPUT_ASSERTION,
+    CAPTURE_SOURCES.ACTION_CLICK_ANNOTATION,
+]);
+export function classifyCaptureSource(source) {
+    if (typeof source !== "string" || !source.trim()) {
+        return {
+            mediaKind: null,
+            persistsToResults: false,
+            visibility: "none",
+        };
+    }
+    if (HIDDEN_DEBUG_MEDIA_KINDS.has(source)) {
+        return {
+            mediaKind: "hidden-debug",
+            persistsToResults: false,
+            visibility: "debug",
+        };
+    }
+    if (CLICK_ANNOTATION_MEDIA_KINDS.has(source)) {
+        return {
+            mediaKind: "click-annotation",
+            persistsToResults: true,
+            visibility: "user",
+        };
+    }
+    if (SCREENSHOT_MEDIA_KINDS.has(source)) {
+        return {
+            mediaKind: "screenshot",
+            persistsToResults: true,
+            visibility: "user",
+        };
+    }
+    return {
+        mediaKind: null,
+        persistsToResults: USER_VISIBLE_RESULT_CAPTURE_SOURCES.has(source),
+        visibility: source === CAPTURE_SOURCES.INSTRUCTION_INPUT || source === CAPTURE_SOURCES.DESIGN_INPUT ? "user" : "none",
+    };
+}

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

@@ -0,0 +1,36 @@
+export const DEFAULT_CONTEXT_OPTIMIZATION_ENABLED = true;
+export const DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD = 30000;
+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";
+export const CONTEXT_OPTIMIZATION_THRESHOLD_ENV = "DROID_CUA_CONTEXT_OPTIMIZATION_THRESHOLD";
+export function normalizeContextOptimizationEnabled(value) {
+    if (typeof value !== "boolean") {
+        return DEFAULT_CONTEXT_OPTIMIZATION_ENABLED;
+    }
+    return value;
+}
+export function normalizeContextOptimizationThreshold(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD;
+    }
+    const normalized = Math.round(value);
+    if (normalized < MIN_CONTEXT_OPTIMIZATION_THRESHOLD) {
+        return MIN_CONTEXT_OPTIMIZATION_THRESHOLD;
+    }
+    if (normalized > MAX_CONTEXT_OPTIMIZATION_THRESHOLD) {
+        return MAX_CONTEXT_OPTIMIZATION_THRESHOLD;
+    }
+    return normalized;
+}
+export function readContextOptimizationEnv(env = process.env) {
+    const rawEnabled = env[CONTEXT_OPTIMIZATION_ENABLED_ENV];
+    const enabled = rawEnabled == null
+        ? DEFAULT_CONTEXT_OPTIMIZATION_ENABLED
+        : !["0", "false", "off", "no"].includes(String(rawEnabled).trim().toLowerCase());
+    const rawThreshold = env[CONTEXT_OPTIMIZATION_THRESHOLD_ENV];
+    const threshold = rawThreshold == null || String(rawThreshold).trim() === ""
+        ? DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD
+        : normalizeContextOptimizationThreshold(Number(rawThreshold));
+    return { enabled, threshold };
+}

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

@@ -8,6 +8,8 @@ import { emitDesktopDebug } from "../utils/desktop-debug.js";
 import { getConfiguredStepDelayMs } from "../utils/step-delay.js";
 import { printCliOutput } from "../utils/console-output.js";
 import { annotateScreenshotArtifact, createAnnotatedScreenshotFromBase64 } from "../utils/run-screenshot-recorder.js";
+import { CAPTURE_SOURCES } from "./capture-sources.js";
+const VALID_CUA_MODELS = new Set(["gpt-5.4", "gpt-5.4-mini", "computer-use-preview"]);
 function extractActionableOutputItems(items) {
     const entries = [];
     for (const item of items) {
@@ -318,23 +320,51 @@ export class ExecutionEngine {
                 }));
             }
             const previewEventId = randomUUID();
-            await this.recordPreviewScreenshot(previewResult.screenshotBase64, {
+            const previewScreenshotResult = await this.recordPreviewScreenshot(previewResult.screenshotBase64, {
                 runId: context?.runId,
                 sessionId: context?.sessionId,
                 stepId: stepContext?.stepId,
                 instructionIndex: stepContext?.instructionIndex,
                 callId,
                 eventId: previewEventId,
-                captureSource: "preview-click",
+                captureSource: CAPTURE_SOURCES.PREVIEW_CLICK,
             });
+            const previewText = buildPreviewOutputText({
+                requestedX: previewResult.marker.requestedX,
+                requestedY: previewResult.marker.requestedY,
+                renderedX: previewResult.marker.x,
+                renderedY: previewResult.marker.y,
+                wasClamped: previewResult.marker.wasClamped,
+            });
+            const addOutput = context?.addOutput || null;
+            if (addOutput) {
+                const previewScreenshotPath = screenshotPathFromRecorderResult(previewScreenshotResult);
+                const previewScreenshotDataUrl = context?.includeScreenshotDataUrl
+                    ? `data:image/png;base64,${previewResult.screenshotBase64}`
+                    : null;
+                addOutput({
+                    type: "action",
+                    text: "Click",
+                    eventType: "tool_call",
+                    runId: context?.runId,
+                    stepId: stepContext?.stepId,
+                    instructionIndex: stepContext?.instructionIndex,
+                    payload: {
+                        platform: this.session.deviceInfo?.platform,
+                        toolName: "preview_click",
+                        captureSource: CAPTURE_SOURCES.PREVIEW_CLICK,
+                        requestedX: previewResult.marker.requestedX,
+                        requestedY: previewResult.marker.requestedY,
+                        renderedX: previewResult.marker.x,
+                        renderedY: previewResult.marker.y,
+                        wasClamped: previewResult.marker.wasClamped,
+                        ...(previewScreenshotPath ? { screenshotPath: previewScreenshotPath } : {}),
+                        ...(previewScreenshotDataUrl ? { screenshotDataUrl: previewScreenshotDataUrl } : {})
+                    }
+                });
+            }
             return buildFunctionCallOutputItem(callId, buildPreviewOutputContent({
-                text: buildPreviewOutputText({
-                    requestedX: previewResult.marker.requestedX,
-                    requestedY: previewResult.marker.requestedY,
-                    renderedX: previewResult.marker.x,
-                    renderedY: previewResult.marker.y,
-                    wasClamped: previewResult.marker.wasClamped,
-                }),
+                text: previewText,
                 annotatedScreenshotBase64: previewResult.screenshotBase64,
             }));
         }
@@ -464,7 +494,7 @@ export class ExecutionEngine {
                         stepId: stepContext?.stepId,
                         instructionIndex: stepContext?.instructionIndex,
                         eventId: actionEventId,
-                        captureSource: "action-click-annotation"
+                        captureSource: CAPTURE_SOURCES.ACTION_CLICK_ANNOTATION
                     });
                     const annotatedScreenshotPath = screenshotPathFromRecorderResult(annotatedScreenshotResult);
                     const annotatedScreenshotDataUrl = screenshotDataUrlFromRecorderResult(annotatedScreenshotResult);
@@ -474,6 +504,7 @@ export class ExecutionEngine {
                         stepId: stepContext?.stepId,
                         instructionIndex: stepContext?.instructionIndex,
                         eventId: actionEventId,
+                        captureSource: CAPTURE_SOURCES.ACTION_CLICK_ANNOTATION,
                         ...(annotatedScreenshotPath ? { screenshotPath: annotatedScreenshotPath } : {}),
                         ...(context?.includeScreenshotDataUrl && annotatedScreenshotDataUrl ? { screenshotDataUrl: annotatedScreenshotDataUrl } : {})
                     });
@@ -504,7 +535,7 @@ export class ExecutionEngine {
                 base64Length: screenshotBase64.length
             });
             const screenshotEventId = randomUUID();
-            const captureSource = sawExplicitScreenshotAction ? "call-output-explicit-action" : "call-output-post-action";
+            const captureSource = sawExplicitScreenshotAction ? CAPTURE_SOURCES.CALL_OUTPUT_EXPLICIT_ACTION : CAPTURE_SOURCES.CALL_OUTPUT_POST_ACTION;
             const screenshotResult = await this.recordScreenshot(screenshotBase64, {
                 runId: context?.runId,
                 sessionId: context?.sessionId,
@@ -548,7 +579,9 @@ export class ExecutionEngine {
                     note: runtimeNote
                 });
             }
-            const selectedCuaModel = process.env.OPENAI_CUA_MODEL === "computer-use-preview" ? "computer-use-preview" : "gpt-5.4";
+            const selectedCuaModel = VALID_CUA_MODELS.has(process.env.OPENAI_CUA_MODEL)
+                ? process.env.OPENAI_CUA_MODEL
+                : "gpt-5.4";
             const input = [{
                     type: "computer_call_output",
                     call_id,

package/build/src/core/prompts.js

@@ -1,3 +1,3 @@
 export { buildBaseSystemPrompt } from "../prompts/base.js";
 export { buildDesignModePrompt, buildDesignRecoveryPrompt } from "../prompts/design.js";
-export { buildAppContextSection, buildAssertionSystemPrompt, buildExecutionModePrompt, buildExecutionRecoveryPrompt, } from "../prompts/execution.js";
+export { buildAppContextSection, buildAssertionSystemPrompt, buildExecutionModePrompt, buildExecutionNavigationRecoveryPrompt, buildExecutionRecoveryPrompt, } from "../prompts/execution.js";

package/build/src/core/session.js

@@ -1,11 +1,18 @@
 /**
  * Session manages the state for a single CLI session
- * Includes device info, message history, transcript, and response chaining
+ * Includes target info, message history, transcript, and response chaining
  */
 export class Session {
-    constructor(deviceId, deviceInfo) {
-        this.deviceId = deviceId;
-        this.deviceInfo = deviceInfo;
+    constructor(targetSessionId, targetInfo) {
+        this.deviceId = targetSessionId;
+        this.deviceInfo = targetInfo;
+        this.deviceName = targetInfo?.device_name || null;
+        this.browserSessionId = targetInfo?.platform === "browser" ? targetSessionId : null;
+        this.browserInfo = targetInfo?.platform === "browser" ? targetInfo : null;
+        this.browserName = targetInfo?.browserName || null;
+        this.currentUrl = targetInfo?.currentUrl || null;
+        this.sessionMode = targetInfo?.sessionMode || null;
+        this.targetKind = targetInfo?.platform === "browser" ? "browser" : "mobile";
         this.messages = [];
         this.previousResponseId = null;
         this.transcript = [];
@@ -54,4 +61,11 @@ export class Session {
     updateResponseId(responseId) {
         this.previousResponseId = responseId;
     }
+    /**
+     * Replace the active system prompt for the next turn and start a fresh response chain.
+     */
+    installRecoverySystemPrompt(prompt) {
+        this.messages = [{ role: "system", content: prompt }];
+        this.updateResponseId(null);
+    }
 }

package/build/src/device/action-event-meta.js

@@ -0,0 +1,18 @@
+export function buildActionEventMeta({ context, action, platform, payload = {}, extraPayload = {} }) {
+    return {
+        eventType: "tool_call",
+        actionType: action?.type,
+        runId: context?.runId,
+        stepId: context?.stepId,
+        instructionIndex: context?.instructionIndex,
+        payload: {
+            eventId: context?.eventId,
+            screenshotPath: context?.screenshotPath,
+            screenshotDataUrl: context?.screenshotDataUrl,
+            captureSource: context?.captureSource,
+            platform,
+            ...extraPayload,
+            ...payload,
+        },
+    };
+}

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

@@ -1,6 +1,7 @@
 import { logger } from "../../utils/logger.js";
 import { emitDesktopDebug, truncateForDebug } from "../../utils/desktop-debug.js";
 import { getConfiguredStepDelayMs } from "../../utils/step-delay.js";
+import { buildActionEventMeta } from "../action-event-meta.js";
 import { resolveScrollGesture } from "../scroll-gesture.js";
 import { execAdb } from "./tools.js";
 function adbShell(deviceId, command) {
@@ -33,19 +34,11 @@ function normalizeMobileKeypress(keys = []) {
 }
 export async function handleModelAction(deviceId, action, scale = 1.0, context = null) {
     const addOutput = context?.addOutput || ((item) => console.log(item.text || item));
-    const meta = (payload = {}) => ({
-        eventType: 'tool_call',
-        actionType: action?.type,
-        runId: context?.runId,
-        stepId: context?.stepId,
-        instructionIndex: context?.instructionIndex,
-        payload: {
-            eventId: context?.eventId,
-            screenshotPath: context?.screenshotPath,
-            screenshotDataUrl: context?.screenshotDataUrl,
-            platform: 'android',
-            ...payload
-        }
+    const meta = (payload = {}) => buildActionEventMeta({
+        context,
+        action,
+        platform: 'android',
+        payload
     });
     try {
         const { x, y, x1, y1, x2, y2, text, keys, path } = action;

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

@@ -1,6 +1,7 @@
 import { logger } from "../../utils/logger.js";
 import { emitDesktopDebug, truncateForDebug } from "../../utils/desktop-debug.js";
 import { getConfiguredStepDelayMs } from "../../utils/step-delay.js";
+import { buildActionEventMeta } from "../action-event-meta.js";
 import { getActiveSession, getDevicePixelRatio } from "./connection.js";
 import { resolveScrollGesture } from "../scroll-gesture.js";
 function normalizeMobileKeypress(platform, keys = []) {
@@ -47,20 +48,14 @@ export async function handleModelAction(deviceId, action, scale = 1.0, context =
     const addOutput = context?.addOutput || ((item) => console.log(item.text || item));
     const session = getActiveSession();
     const platform = session?.platform;
-    const meta = (payload = {}) => ({
-        eventType: "tool_call",
-        actionType: action?.type,
-        runId: context?.runId,
-        stepId: context?.stepId,
-        instructionIndex: context?.instructionIndex,
-        payload: {
-            eventId: context?.eventId,
-            screenshotPath: context?.screenshotPath,
-            screenshotDataUrl: context?.screenshotDataUrl,
-            platform,
-            source: session?.providerId,
-            ...payload
-        }
+    const meta = (payload = {}) => buildActionEventMeta({
+        context,
+        action,
+        platform,
+        extraPayload: {
+            source: session?.providerId
+        },
+        payload
     });
     if (!session || !platform) {
         throw new Error("No active cloud session");

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

@@ -103,6 +103,14 @@ export function getActiveSession() {
 export function getDevicePixelRatio() {
     return activeSession?.devicePixelRatio || 1;
 }
+// Test-only — do not call from production code. Used by unit tests to install
+// a fake session without going through the real cloud-provider connect flow.
+export function setActiveSessionForTests(session) {
+    activeSession = session;
+}
+export function clearActiveSessionForTests() {
+    activeSession = null;
+}
 export async function disconnect() {
     if (!activeSession) {
         return;

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

@@ -4,6 +4,7 @@
  * Executes CUA model actions on iOS Simulator via Appium.
  */
 import * as appium from "./appium-client.js";
+import { buildActionEventMeta } from "../action-event-meta.js";
 import { getActiveSession, getDevicePixelRatio } from "./connection.js";
 import { logger } from "../../utils/logger.js";
 import { emitDesktopDebug, truncateForDebug } from "../../utils/desktop-debug.js";
@@ -44,19 +45,11 @@ function normalizeMobileKeypress(keys = []) {
 export async function handleModelAction(simulatorId, action, scale = 1.0, context = null) {
     const addOutput = context?.addOutput || ((item) => console.log(item.text || item));
     const session = getActiveSession();
-    const meta = (payload = {}) => ({
-        eventType: "tool_call",
-        actionType: action?.type,
-        runId: context?.runId,
-        stepId: context?.stepId,
-        instructionIndex: context?.instructionIndex,
-        payload: {
-            eventId: context?.eventId,
-            screenshotPath: context?.screenshotPath,
-            screenshotDataUrl: context?.screenshotDataUrl,
-            platform: "ios",
-            ...payload
-        }
+    const meta = (payload = {}) => buildActionEventMeta({
+        context,
+        action,
+        platform: "ios",
+        payload
     });
     if (!session) {
         throw new Error("No active iOS session");

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

@@ -7,6 +7,7 @@
 import { spawn } from "child_process";
 import { existsSync, readdirSync } from "fs";
 import path from "path";
+import { COMMON_NODE_BIN_DIRS, makeNodeCliCommandEnv } from "./node-cli-env.js";
 let appiumProcess = null;
 let cleanupRegistered = false;
 function getAppiumBaseUrl() {
@@ -35,8 +36,7 @@ export function resolveAppiumCommand() {
         return explicit;
     }
     const commonCandidates = [
-        "/opt/homebrew/bin/appium",
-        "/usr/local/bin/appium",
+        ...COMMON_NODE_BIN_DIRS.map((dir) => path.join(dir, "appium")),
         ...collectNvmAppiumCandidates()
     ];
     for (const candidate of commonCandidates) {
@@ -50,7 +50,8 @@ async function spawnAppiumProcess(command) {
     return await new Promise((resolve, reject) => {
         const child = spawn(command, [], {
             detached: true,
-            stdio: "ignore"
+            stdio: "ignore",
+            env: makeNodeCliCommandEnv(command)
         });
         child.once("error", reject);
         child.once("spawn", () => resolve(child));

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

@@ -299,6 +299,14 @@ export function getActiveSession() {
 export function getDevicePixelRatio() {
     return activeSession?.devicePixelRatio || 3;
 }
+// Test-only — do not call from production code. Used by unit tests to install
+// a fake session without going through the real Appium/simulator boot flow.
+export function setActiveSessionForTests(session) {
+    activeSession = session;
+}
+export function clearActiveSessionForTests() {
+    activeSession = null;
+}
 /**
  * Disconnect and cleanup
  */

package/build/src/device/ios/node-cli-env.js

@@ -0,0 +1,28 @@
+import path from "path";
+export const COMMON_NODE_BIN_DIRS = ["/opt/homebrew/bin", "/usr/local/bin", "/opt/local/bin"];
+function prependPathEntries(entries, originalPath) {
+    const seen = new Set();
+    const next = [];
+    const allEntries = [
+        ...entries,
+        ...(originalPath
+            ?.split(path.delimiter)
+            .map((entry) => entry.trim())
+            .filter(Boolean) ?? [])
+    ];
+    for (const entry of allEntries) {
+        if (seen.has(entry))
+            continue;
+        seen.add(entry);
+        next.push(entry);
+    }
+    return next.join(path.delimiter);
+}
+export function makeNodeCliCommandEnv(command) {
+    const binDirs = path.isAbsolute(command) ? [path.dirname(command), ...COMMON_NODE_BIN_DIRS] : COMMON_NODE_BIN_DIRS;
+    return {
+        ...process.env,
+        // Finder-launched apps may miss Homebrew paths; npm/Appium shims use "#!/usr/bin/env node".
+        PATH: prependPathEntries(binDirs, process.env.PATH)
+    };
+}

package/build/src/device/openai.js

@@ -1,12 +1,14 @@
 import OpenAI from "openai";
+import { readContextOptimizationEnv } from "../core/context-optimization.js";
 import { buildTestRevisionSystemPrompt } from "../prompts/editor.js";
 import { buildAppContextCompactionInput } from "../prompts/execution.js";
 import { logger } from "../utils/logger.js";
 import { CuaDebugTracer } from "../utils/cua-debug-tracer.js";
 let openai = null;
 const cuaDebugTracer = new CuaDebugTracer(logger);
+const VALID_CUA_MODELS = new Set(["gpt-5.4", "gpt-5.4-mini", "computer-use-preview"]);
 function getSelectedCuaModel() {
-    return process.env.OPENAI_CUA_MODEL === "computer-use-preview" ? "computer-use-preview" : "gpt-5.4";
+    return VALID_CUA_MODELS.has(process.env.OPENAI_CUA_MODEL) ? process.env.OPENAI_CUA_MODEL : "gpt-5.4";
 }
 function normalizeMessageContent(content) {
     if (Array.isArray(content)) {
@@ -88,7 +90,18 @@ export function buildCuaInput({ messages, screenshotBase64, previousResponseId,
     }
     return input;
 }
+function buildContextManagement(cuaModel) {
+    if (cuaModel === "computer-use-preview") {
+        return undefined;
+    }
+    const { enabled, threshold } = readContextOptimizationEnv();
+    if (!enabled) {
+        return undefined;
+    }
+    return [{ type: "compaction", compact_threshold: threshold }];
+}
 export function buildCuaRequestParams({ cuaModel, previousResponseId, deviceInfo, input }) {
+    const contextManagement = buildContextManagement(cuaModel);
     if (cuaModel === "computer-use-preview") {
         return {
             model: cuaModel,
@@ -111,6 +124,7 @@ export function buildCuaRequestParams({ cuaModel, previousResponseId, deviceInfo
     return {
         model: cuaModel,
         reasoning: { effort: "medium" },
+        ...(contextManagement ? { context_management: contextManagement } : {}),
         previous_response_id: previousResponseId || undefined,
         input,
         store: true,
@@ -137,12 +151,41 @@ function shouldMapPreviewAccessError(err) {
     return (message.includes("computer-use-preview") &&
         (message.includes("access") || message.includes("permission") || message.includes("not found") || message.includes("unsupported")));
 }
+export function shouldMapMiniCompatibilityError(err) {
+    const status = Number(err?.status);
+    const code = typeof err?.code === "string" ? err.code.toLowerCase() : "";
+    const type = typeof err?.type === "string" ? err.type.toLowerCase() : "";
+    const message = typeof err?.message === "string" ? err.message.toLowerCase() : "";
+    const mentionsMiniModel = message.includes("gpt-5.4-mini");
+    const mentionsComputerTool = message.includes("computer") || message.includes("tool");
+    const mentionsUnsupported = (message.includes("unsupported") ||
+        message.includes("not supported") ||
+        message.includes("does not support"));
+    if (code.includes("model_not_found")) {
+        return true;
+    }
+    if (status === 404) {
+        return mentionsMiniModel && (message.includes("not found") || mentionsUnsupported);
+    }
+    if (code.includes("unsupported")) {
+        return mentionsMiniModel || mentionsComputerTool;
+    }
+    if (!type.includes("invalid")) {
+        return false;
+    }
+    return mentionsUnsupported && (mentionsMiniModel || mentionsComputerTool);
+}
 function mapCuaError(err, cuaModel) {
     if (cuaModel === "computer-use-preview" && shouldMapPreviewAccessError(err)) {
         const mapped = new Error("OpenAI API key does not have access to computer-use-preview. Switch to gpt-5.4 in Settings > CUA Model.");
         mapped.cause = err;
         return mapped;
     }
+    if (cuaModel === "gpt-5.4-mini" && shouldMapMiniCompatibilityError(err)) {
+        const mapped = new Error("OpenAI rejected gpt-5.4-mini for computer-use execution. Switch to gpt-5.4 or computer-use-preview in Settings > CUA Model.");
+        mapped.cause = err;
+        return mapped;
+    }
     return err;
 }
 export function isNonRetryableCuaError(err) {
@@ -157,7 +200,9 @@ export function isNonRetryableCuaError(err) {
         code.includes("permission") ||
         type.includes("permission") ||
         message.includes("does not have access to computer-use-preview") ||
-        message.includes("switch to gpt-5.4 in settings > cua model"));
+        message.includes("switch to gpt-5.4 in settings > cua model") ||
+        message.includes("openai rejected gpt-5.4-mini for computer-use execution") ||
+        message.includes("switch to gpt-5.4 or computer-use-preview in settings > cua model"));
 }
 function getOpenAI() {
     if (!openai) {