@loadmill/droid-cua 2.15.1 → 2.16.0

package/README.md

@@ -46,9 +46,9 @@ Under the hood, `droid-cua` uses an AI agent to explore your app, execute action
 
 Open the desktop app and choose the platform you want to test.
 
-**3. Add your credentials**
+**3. Choose your AI provider**
 
-Set your OpenAI API key in the app Settings screen, or log in with your Loadmill account.
+In Settings, choose the CUA model you want to run. `Loadmill - Smart` uses your Loadmill sign-in and usage tracking. The OpenAI models use your own OpenAI API key.
 
 **4. Connect a target device**
 
@@ -75,7 +75,7 @@ Desktop app support:
 ## Requirements
 
 **All platforms:**
-- OpenAI API key
+- Loadmill sign-in for `Loadmill - Smart`, or an OpenAI API key for the OpenAI models
 
 **Android:**
 - Android Debug Bridge (ADB)

package/build/index.js

@@ -29,6 +29,7 @@ const targetConfig = resolveHeadlessTarget(args);
 let avdName = targetConfig.avdName;
 let platform = targetConfig.platform || null; // 'ios' or 'android'
 const recordScreenshots = args["record"] || false;
+const startupUrl = typeof args.url === "string" && args.url.trim().length > 0 ? args.url.trim() : null;
 const instructionsFile = args.instructions || args.i || null;
 const appContextPath = typeof args.context === "string" ? args.context : null;
 const debugMode = args["debug"] || false;
@@ -149,6 +150,7 @@ async function main() {
     let deviceInfo;
     if (isBrowserTarget) {
         targetId = await connectToBrowser({
+            url: startupUrl,
             headless: true,
             browserFamily: targetConfig.browserFamily,
             sessionMode: targetConfig.sessionMode
@@ -219,6 +221,7 @@ async function main() {
             const appContext = preloadedAppContext;
             const appContextText = appContext.text;
             const runtimeContext = createCliRuntimeContext({
+                llmProviderMode: headlessConfig.llmProviderMode,
                 cuaModel: headlessConfig.cuaModel,
                 promptCustomizations: headlessConfig.promptCustomizations,
                 contextOptimizationEnabled: headlessConfig.contextOptimizationEnabled,
@@ -231,6 +234,8 @@ async function main() {
                     message: appContext.message,
                 },
             });
+            console.log(`Using AI provider: ${runtimeContext.config.llmProviderMode}`);
+            console.log(`Using CUA model: ${runtimeContext.config.cuaModel}`);
             const result = await runHeadlessInstructionRuns({
                 runs: headlessInstructionRuns,
                 instructionsTarget: preloadedHeadlessTarget,

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

@@ -2,7 +2,8 @@ import path from "path";
 import { readFile } from "fs/promises";
 import { DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD, MAX_CONTEXT_OPTIMIZATION_THRESHOLD, MIN_CONTEXT_OPTIMIZATION_THRESHOLD, } from "../core/context-optimization.js";
 import { AIM_ASSIST_MODES, DEFAULT_AIM_ASSIST_MODE } from "../core/aim-assist.js";
-import { CUA_MODELS, isValidCuaModel, resolveCuaModel } from "../core/cua-models.js";
+import { CUA_MODELS, DEFAULT_OPENAI_CUA_MODEL, isOpenAiCuaModel, isValidCuaModel, resolveCuaModel } from "../core/cua-models.js";
+import { LLM_PROVIDER_MODES, isValidLlmProviderMode, resolveLlmProviderMode } from "../core/runtime-config.js";
 function createEmptyPromptCustomizations() {
     return {
         basePromptInstructions: "",
@@ -30,8 +31,25 @@ function validateAimAssistMode(value, label) {
     }
     return value;
 }
+function validateLlmProviderMode(value, label) {
+    if (typeof value !== "string" || !isValidLlmProviderMode(value)) {
+        throw new Error(`${label} must be one of: ${LLM_PROVIDER_MODES.join(", ")}.`);
+    }
+    return value;
+}
 function readEnvDefaultCuaModel() {
-    return resolveCuaModel(process.env.OPENAI_CUA_MODEL);
+    const envValue = process.env.OPENAI_CUA_MODEL;
+    // OPENAI_CUA_MODEL only selects OpenAI models. If it is set but not a valid
+    // OpenAI model, stay on the OpenAI default rather than crossing over to the
+    // global (Loadmill) default.
+    if (typeof envValue === "string" && envValue.trim()) {
+        const trimmed = envValue.trim();
+        return isOpenAiCuaModel(trimmed) ? trimmed : DEFAULT_OPENAI_CUA_MODEL;
+    }
+    return resolveCuaModel(envValue);
+}
+function readEnvDefaultLlmProviderMode() {
+    return resolveLlmProviderMode(process.env.DROID_CUA_LLM_PROVIDER);
 }
 function parseContextOptimizationThreshold(rawValue, label) {
     const numericValue = (() => {
@@ -107,6 +125,7 @@ async function loadConfigFromFile(configPath) {
     const configDir = path.dirname(absoluteConfigPath);
     const normalized = {
         configPath: absoluteConfigPath,
+        llmProviderMode: undefined,
         cuaModel: undefined,
         aimAssistMode: undefined,
         promptCustomizations: createEmptyPromptCustomizations(),
@@ -115,6 +134,9 @@ async function loadConfigFromFile(configPath) {
         contextOptimizationEnabled: undefined,
         contextOptimizationThreshold: undefined,
     };
+    if ("llmProviderMode" in rawConfig) {
+        normalized.llmProviderMode = validateLlmProviderMode(rawConfig.llmProviderMode, "config.llmProviderMode");
+    }
     if ("cuaModel" in rawConfig) {
         normalized.cuaModel = validateCuaModel(rawConfig.cuaModel, "config.cuaModel");
     }
@@ -174,6 +196,7 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     };
     const resolved = {
         configPath: fileConfig?.configPath || null,
+        llmProviderMode: fileConfig?.llmProviderMode || readEnvDefaultLlmProviderMode(),
         cuaModel: fileConfig?.cuaModel || readEnvDefaultCuaModel(),
         aimAssistMode: fileConfig?.aimAssistMode || DEFAULT_AIM_ASSIST_MODE,
         promptCustomizations,
@@ -182,6 +205,9 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
         contextOptimizationEnabled: fileConfig?.contextOptimizationEnabled ?? true,
         contextOptimizationThreshold: fileConfig?.contextOptimizationThreshold ?? DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD,
     };
+    if (typeof args["llm-provider"] === "string") {
+        resolved.llmProviderMode = validateLlmProviderMode(args["llm-provider"], "--llm-provider");
+    }
     if (typeof args["cua-model"] === "string") {
         resolved.cuaModel = validateCuaModel(args["cua-model"], "--cua-model");
     }

package/build/src/cli/ink-shell.js

@@ -35,6 +35,7 @@ export async function startInkShell(session, executionEngine, options = {}) {
                 engine: executionEngine,
                 appContextPath: options.appContextPath ?? null,
                 runtimeContext: options.runtimeContext ?? null,
+                runtimeConfig: options.runtimeContext?.config ?? null,
                 openAiClient: options.runtimeContext?.openAiClient ?? null,
                 loadmillClient: options.runtimeContext?.loadmillClient ?? null,
                 runtimeCredentials: options.runtimeContext?.credentials ?? null

package/build/src/commands/help.js

@@ -28,7 +28,8 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  --instructions <file>  Run test file in headless mode' });
     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 gpt-5.4-mini' });
+    addOutput({ type: 'info', text: '  --llm-provider <mode>  Headless AI provider: loadmill or openai' });
+    addOutput({ type: 'info', text: '  --cua-model <model>    Headless CUA model override: gpt-5.4, loadmill-smart, or gpt-5.4-mini' });
     addOutput({ type: 'info', text: '  --aim-assist <mode>    Headless Aim Assist mode: off, smart, or always' });
     addOutput({ type: 'info', text: '  --context <file>       Optional app context file injected into execution runs' });
     addOutput({ type: 'info', text: '  --no-context           Disable app context for headless execution' });

package/build/src/commands/loadmill.js

@@ -2,7 +2,7 @@
  * Loadmill command handler
  */
 import { createLoadmillApiClient, executeLoadmillCommand, getApiToken } from "../integrations/loadmill/index.js";
-import { createOpenAiClient, resolveRuntimeCredentialsFromEnv } from "../core/runtime-config.js";
+import { createResolvedLlmClient, resolveRuntimeConfigFromEnv, resolveRuntimeCredentialsFromEnv, } from "../core/runtime-config.js";
 /**
  * Handle /loadmill command
  * @param {string} args - Command arguments (natural language command)
@@ -48,33 +48,60 @@ export async function handleLoadmill(args, session, context) {
     if (context.setAgentWorking) {
         context.setAgentWorking(true, 'Running Loadmill flow...');
     }
-    const runtimeCredentials = context.runtimeCredentials || resolveRuntimeCredentialsFromEnv();
-    const loadmillClient = context.loadmillClient || createLoadmillApiClient({
-        token: runtimeCredentials.loadmillApiToken,
-        baseUrl: runtimeCredentials.loadmillBaseUrl,
-    });
-    const openAiClient = context.openAiClient || createOpenAiClient(runtimeCredentials.openAiApiKey);
-    // Execute the command
-    const result = await executeLoadmillCommand(command, {
-        loadmillClient,
-        openAiClient,
-        onProgress: ({ message }) => {
-            addOutput({ type: 'info', text: `[Loadmill] ${message}` });
+    try {
+        const runtimeCredentials = context.runtimeCredentials || resolveRuntimeCredentialsFromEnv();
+        const runtimeConfig = context.runtimeConfig || resolveRuntimeConfigFromEnv();
+        const loadmillClient = context.loadmillClient || createLoadmillApiClient({
+            token: runtimeCredentials.loadmillApiToken,
+            baseUrl: runtimeCredentials.loadmillBaseUrl,
+        });
+        const openAiClient = context.openAiClient || createResolvedLlmClient({
+            llmProviderMode: runtimeConfig.llmProviderMode,
+            credentials: runtimeCredentials,
+            clientName: "cli",
+        });
+        // Execute the command
+        const result = await executeLoadmillCommand(command, {
+            loadmillClient,
+            openAiClient,
+            onProgress: ({ message }) => {
+                addOutput({ type: 'info', text: `[Loadmill] ${message}` });
+            }
+        });
+        // Display results
+        if (result.success) {
+            if (result.action === "search") {
+                addOutput({ type: 'success', text: `Found ${result.result.flows.length} flow(s):` });
+                result.result.flows.forEach((flow, i) => {
+                    const name = flow.description || flow.name || "Unknown";
+                    const suite = flow.testSuiteDescription ? ` (Suite: ${flow.testSuiteDescription})` : '';
+                    addOutput({ type: 'info', text: `  ${i + 1}. ${name}${suite}` });
+                    addOutput({ type: 'info', text: `     ID: ${flow.id}` });
+                });
+                if (result.result.selectedFlow) {
+                    const selectedName = result.result.selectedFlow.description || result.result.selectedFlow.name || "Unknown";
+                    addOutput({ type: 'info', text: '' });
+                    addOutput({ type: 'info', text: `Best match: "${selectedName}" (confidence: ${(result.result.confidence * 100).toFixed(0)}%)` });
+                }
+            }
+            else {
+                addOutput({ type: 'success', text: `Flow "${result.flowName}" passed` });
+                if (result.runId) {
+                    addOutput({ type: 'info', text: `Run ID: ${result.runId}` });
+                }
+            }
         }
-    });
-    // Clear agent working status
-    if (context.setAgentWorking) {
-        context.setAgentWorking(false);
-    }
-    // Display results
-    if (result.success) {
-        addOutput({ type: 'success', text: `Flow "${result.flowName}" passed` });
-        if (result.runId) {
-            addOutput({ type: 'info', text: `Run ID: ${result.runId}` });
+        else {
+            addOutput({ type: 'error', text: `Loadmill failed: ${result.error}` });
         }
     }
-    else {
-        addOutput({ type: 'error', text: `Loadmill failed: ${result.error}` });
+    catch (error) {
+        addOutput({ type: 'error', text: error instanceof Error ? error.message : 'Loadmill command failed.' });
+    }
+    finally {
+        if (context.setAgentWorking) {
+            context.setAgentWorking(false);
+        }
     }
     return true; // Continue loop
 }

package/build/src/core/cua-backends.js

@@ -0,0 +1,11 @@
+export const CUA_BACKENDS = ["openai", "fara"];
+export const DEFAULT_CUA_BACKEND = "openai";
+export const DEFAULT_FARA_BASE_URL = "http://localhost:5000/v1";
+export const DEFAULT_FARA_MODEL = "Fara-7B";
+const VALID_CUA_BACKENDS = new Set(CUA_BACKENDS);
+export function isValidCuaBackend(value) {
+    return VALID_CUA_BACKENDS.has(value);
+}
+export function resolveCuaBackend(value) {
+    return isValidCuaBackend(value) ? value : DEFAULT_CUA_BACKEND;
+}

package/build/src/core/cua-models.js

@@ -1,9 +1,54 @@
-export const CUA_MODELS = ["gpt-5.4", "gpt-5.4-mini"];
-export const DEFAULT_CUA_MODEL = "gpt-5.4";
+export const DEFAULT_OPENAI_CUA_MODEL = "gpt-5.4";
+export const DEFAULT_LOADMILL_CUA_MODEL = "loadmill-smart";
+export const DEFAULT_CUA_MODEL = DEFAULT_LOADMILL_CUA_MODEL;
+export const OPENAI_CUA_MODELS = ["gpt-5.4", "gpt-5.4-mini"];
+export const LOADMILL_CUA_MODELS = [DEFAULT_LOADMILL_CUA_MODEL];
+export const CUA_MODELS = ["gpt-5.4", "loadmill-smart", "gpt-5.4-mini"];
+export const CUA_MODEL_OPTIONS = Object.freeze([
+    Object.freeze({
+        id: "loadmill-smart",
+        providerMode: "loadmill",
+        providerLabel: "Loadmill",
+        name: "Loadmill Smart",
+        label: "Loadmill Smart (recommended)",
+    }),
+    Object.freeze({
+        id: "gpt-5.4",
+        providerMode: "openai",
+        providerLabel: "OpenAI",
+        name: "GPT-5.4",
+        label: "OpenAI GPT-5.4",
+    }),
+    Object.freeze({
+        id: "gpt-5.4-mini",
+        providerMode: "openai",
+        providerLabel: "OpenAI",
+        name: "GPT-5.4 mini",
+        label: "OpenAI GPT-5.4 mini (faster)",
+    }),
+]);
 const VALID_CUA_MODELS = new Set(CUA_MODELS);
+const OPENAI_CUA_MODEL_SET = new Set(OPENAI_CUA_MODELS);
+const LOADMILL_CUA_MODEL_SET = new Set(LOADMILL_CUA_MODELS);
+const CUA_MODEL_PROVIDER_MODE_MAP = new Map(CUA_MODEL_OPTIONS.map((option) => [option.id, option.providerMode]));
 export function isValidCuaModel(value) {
     return VALID_CUA_MODELS.has(value);
 }
+export function isOpenAiCuaModel(value) {
+    return OPENAI_CUA_MODEL_SET.has(value);
+}
+export function isLoadmillCuaModel(value) {
+    return LOADMILL_CUA_MODEL_SET.has(value);
+}
 export function resolveCuaModel(value) {
     return isValidCuaModel(value) ? value : DEFAULT_CUA_MODEL;
 }
+export function resolveCuaModelProviderMode(value) {
+    const normalized = resolveCuaModel(value);
+    return CUA_MODEL_PROVIDER_MODE_MAP.get(normalized) || "openai";
+}
+export function resolveDefaultCuaModelForProvider(providerMode) {
+    return providerMode === "loadmill"
+        ? DEFAULT_LOADMILL_CUA_MODEL
+        : DEFAULT_OPENAI_CUA_MODEL;
+}

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

@@ -1,7 +1,26 @@
 import OpenAI from "openai";
+import { normalizeOptionalAutomationUrl } from "../browser/playwright/url.js";
 import { readContextOptimizationEnv, normalizeContextOptimizationEnabled, normalizeContextOptimizationThreshold, } from "./context-optimization.js";
-import { resolveCuaModel } from "./cua-models.js";
+import { DEFAULT_OPENAI_CUA_MODEL, isLoadmillCuaModel, resolveCuaModel, resolveCuaModelProviderMode, } from "./cua-models.js";
+import { DEFAULT_FARA_BASE_URL, DEFAULT_FARA_MODEL, resolveCuaBackend, } from "./cua-backends.js";
 import { normalizeStepDelayMs } from "../utils/step-delay.js";
+export const LOADMILL_MODEL_ALIASES = Object.freeze({
+    DEFAULT_AGENT_MODEL: "default-agent-model",
+    FAST: "fast",
+    SMART: "smart",
+    COMPUTER_USE: "computer-use",
+});
+const LOADMILL_MODEL_ALIAS_SET = new Set(Object.values(LOADMILL_MODEL_ALIASES));
+export const LLM_PROVIDER_MODES = Object.freeze(["loadmill", "openai"]);
+export const DEFAULT_LLM_PROVIDER_MODE = "loadmill";
+export const DEFAULT_LOADMILL_BASE_URL = "https://app.loadmill.com";
+const VALID_LLM_PROVIDER_MODES = new Set(LLM_PROVIDER_MODES);
+export function isValidLlmProviderMode(value) {
+    return VALID_LLM_PROVIDER_MODES.has(value);
+}
+export function resolveLlmProviderMode(value) {
+    return isValidLlmProviderMode(value) ? value : DEFAULT_LLM_PROVIDER_MODE;
+}
 export function createEmptyPromptCustomizations() {
     return {
         basePromptInstructions: "",
@@ -28,16 +47,95 @@ function trimNullableString(value) {
     const trimmed = value.trim();
     return trimmed || null;
 }
-export function resolveRuntimeCredentials({ openAiApiKey = null, loadmillApiToken = null, loadmillBaseUrl = null, } = {}) {
+function normalizeLoadmillSiteBaseUrl(value) {
+    const trimmed = trimNullableString(value) || DEFAULT_LOADMILL_BASE_URL;
+    const normalizedCandidate = normalizeOptionalAutomationUrl(trimmed) || trimmed;
+    try {
+        const parsed = new URL(normalizedCandidate);
+        const pathname = parsed.pathname.replace(/\/+$/, "");
+        parsed.pathname = pathname
+            .replace(/\/api$/, "")
+            .replace(/\/llm\/v1$/, "")
+            .replace(/\/llm$/, "");
+        parsed.search = "";
+        parsed.hash = "";
+        return parsed.toString().replace(/\/$/, "");
+    }
+    catch {
+        return normalizedCandidate
+            .replace(/\/api\/?$/, "")
+            .replace(/\/llm\/v1\/?$/, "")
+            .replace(/\/llm\/?$/, "")
+            .replace(/\/$/, "") || null;
+    }
+}
+export function buildLoadmillLlmBaseUrl(value) {
+    const siteBaseUrl = normalizeLoadmillSiteBaseUrl(value);
+    return siteBaseUrl ? `${siteBaseUrl}/llm/v1` : null;
+}
+export function hasLoadmillLlmAccess(credentials = {}) {
+    return Boolean(trimNullableString(credentials.loadmillApiToken) &&
+        buildLoadmillLlmBaseUrl(credentials.loadmillBaseUrl));
+}
+export function hasOpenAiLlmAccess(credentials = {}) {
+    return Boolean(trimNullableString(credentials.openAiApiKey));
+}
+export function inferLlmProviderModeFromCredentials(credentials = {}) {
+    if (hasLoadmillLlmAccess(credentials)) {
+        return "loadmill";
+    }
+    if (hasOpenAiLlmAccess(credentials)) {
+        return "openai";
+    }
+    return DEFAULT_LLM_PROVIDER_MODE;
+}
+export function resolveGatewayCuaModelAlias({ cuaBackend, cuaModel } = {}) {
+    if (resolveCuaBackend(cuaBackend) === "fara") {
+        return LOADMILL_MODEL_ALIASES.COMPUTER_USE;
+    }
+    const normalizedCuaModel = resolveCuaModel(cuaModel);
+    return normalizedCuaModel === "gpt-5.4-mini"
+        ? LOADMILL_MODEL_ALIASES.FAST
+        : LOADMILL_MODEL_ALIASES.SMART;
+}
+export function resolveEffectiveCuaModel({ llmProviderMode = null, cuaBackend = null, cuaModel = null, } = {}) {
+    const providerMode = resolveLlmProviderMode(llmProviderMode);
+    if (providerMode === "loadmill") {
+        return resolveGatewayCuaModelAlias({ cuaBackend, cuaModel });
+    }
+    return resolveCuaModelProviderMode(cuaModel) === "openai"
+        ? resolveCuaModel(cuaModel)
+        : DEFAULT_OPENAI_CUA_MODEL;
+}
+export function resolveEffectiveHelperModel({ llmProviderMode = null, cuaModel = null, } = {}) {
+    if (resolveLlmProviderMode(llmProviderMode) === "loadmill") {
+        return LOADMILL_MODEL_ALIASES.DEFAULT_AGENT_MODEL;
+    }
+    return resolveCuaModelProviderMode(cuaModel) === "openai"
+        ? resolveCuaModel(cuaModel)
+        : DEFAULT_OPENAI_CUA_MODEL;
+}
+export function resolveRuntimeCredentials({ openAiApiKey = null, faraApiKey = null, faraBaseUrl = null, faraModel = null, loadmillApiToken = null, loadmillBaseUrl = null, } = {}) {
     return {
         openAiApiKey: trimNullableString(openAiApiKey),
+        faraApiKey: trimNullableString(faraApiKey),
+        faraBaseUrl: trimNullableString(faraBaseUrl) || DEFAULT_FARA_BASE_URL,
+        faraModel: trimNullableString(faraModel) || DEFAULT_FARA_MODEL,
         loadmillApiToken: trimNullableString(loadmillApiToken),
-        loadmillBaseUrl: trimNullableString(loadmillBaseUrl),
+        loadmillBaseUrl: normalizeLoadmillSiteBaseUrl(loadmillBaseUrl),
     };
 }
-export function resolveRuntimeConfig({ cuaModel = null, stepDelayMs = undefined, contextOptimizationEnabled = undefined, contextOptimizationThreshold = undefined, promptCustomizations = null, appContext = null, } = {}) {
+export function resolveRuntimeConfig({ llmProviderMode = null, cuaBackend = null, cuaModel = null, stepDelayMs = undefined, contextOptimizationEnabled = undefined, contextOptimizationThreshold = undefined, promptCustomizations = null, appContext = null, } = {}) {
+    const normalizedCuaModel = typeof cuaModel === "string" && LOADMILL_MODEL_ALIAS_SET.has(cuaModel)
+        ? cuaModel
+        : resolveCuaModel(cuaModel);
+    const normalizedProviderMode = resolveLlmProviderMode(llmProviderMode);
     return {
-        cuaModel: resolveCuaModel(cuaModel),
+        llmProviderMode: llmProviderMode == null && isLoadmillCuaModel(normalizedCuaModel)
+            ? "loadmill"
+            : normalizedProviderMode,
+        cuaBackend: resolveCuaBackend(cuaBackend),
+        cuaModel: normalizedCuaModel,
         stepDelayMs: normalizeStepDelayMs(Number(stepDelayMs)),
         contextOptimizationEnabled: normalizeContextOptimizationEnabled(contextOptimizationEnabled),
         contextOptimizationThreshold: normalizeContextOptimizationThreshold(contextOptimizationThreshold),
@@ -62,6 +160,12 @@ export function resolveRuntimeConfig({ cuaModel = null, stepDelayMs = undefined,
 export function resolveRuntimeConfigFromEnv(env = process.env, overrides = {}) {
     const contextOptimization = readContextOptimizationEnv(env);
     return resolveRuntimeConfig({
+        llmProviderMode: env.DROID_CUA_LLM_PROVIDER,
+        // Only the explicit backend flag should influence CUA model routing.
+        // Legacy screenshot-provider env vars must not silently remap Loadmill
+        // model aliases like "smart" to backend-specific aliases like
+        // "computer-use".
+        cuaBackend: env.DROID_CUA_BACKEND,
         cuaModel: env.OPENAI_CUA_MODEL,
         stepDelayMs: env.DROID_CUA_STEP_DELAY_MS,
         contextOptimizationEnabled: contextOptimization.enabled,
@@ -72,6 +176,9 @@ export function resolveRuntimeConfigFromEnv(env = process.env, overrides = {}) {
 export function resolveRuntimeCredentialsFromEnv(env = process.env, overrides = {}) {
     return resolveRuntimeCredentials({
         openAiApiKey: env.OPENAI_API_KEY,
+        faraApiKey: env.DROID_CUA_FARA_API_KEY,
+        faraBaseUrl: env.DROID_CUA_FARA_BASE_URL,
+        faraModel: env.DROID_CUA_FARA_MODEL,
         loadmillApiToken: env.LOADMILL_API_TOKEN,
         loadmillBaseUrl: env.LOADMILL_BASE_URL,
         ...overrides,
@@ -82,14 +189,151 @@ export function createOpenAiClient(apiKey) {
         apiKey: trimNullableString(apiKey) || undefined,
     });
 }
+function missingCredentialErrorMessage(llmProviderMode) {
+    return resolveLlmProviderMode(llmProviderMode) === "loadmill"
+        ? "Loadmill authentication is required to use the Loadmill model."
+        : "An OpenAI API key is required to use OpenAI models.";
+}
+function isLoadmillGatewayErrorPayload(payload) {
+    return Boolean(payload &&
+        typeof payload === "object" &&
+        typeof payload.message === "string" &&
+        typeof payload.type === "string" &&
+        typeof payload.code === "string");
+}
+function normalizeLoadmillGatewayErrorBody(body) {
+    const payload = body?.payload;
+    if (!isLoadmillGatewayErrorPayload(payload)) {
+        return null;
+    }
+    return {
+        error: {
+            message: payload.message,
+            type: payload.type,
+            code: payload.code,
+            param: payload.param ?? null,
+            provider: typeof payload.provider === "string" ? payload.provider : null,
+        },
+    };
+}
+async function normalizeLoadmillGatewayErrorResponse(response) {
+    const contentType = response.headers.get("content-type") || "";
+    if (!contentType.includes("application/json")) {
+        return response;
+    }
+    const responseClone = response.clone();
+    const bodyText = await responseClone.text();
+    if (!bodyText) {
+        return response;
+    }
+    let parsedBody;
+    try {
+        parsedBody = JSON.parse(bodyText);
+    }
+    catch {
+        return response;
+    }
+    const normalizedBody = normalizeLoadmillGatewayErrorBody(parsedBody);
+    if (!normalizedBody) {
+        return response;
+    }
+    const headers = new Headers(response.headers);
+    headers.set("content-type", "application/json");
+    return new Response(JSON.stringify(normalizedBody), {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+function createLoadmillGatewayFetch(baseFetch = fetch) {
+    return async (input, init) => {
+        const response = await baseFetch(input, init);
+        if (response.ok) {
+            return response;
+        }
+        return await normalizeLoadmillGatewayErrorResponse(response);
+    };
+}
+/**
+ * @param {{
+ *   loadmillApiToken?: string | null,
+ *   loadmillBaseUrl?: string | null,
+ *   clientName?: string,
+ *   maxRetries?: number,
+ * }} [options]
+ */
+export function createLlmClient({ loadmillApiToken, loadmillBaseUrl, clientName = "desktop", maxRetries = 1, } = {}) {
+    const apiKey = trimNullableString(loadmillApiToken);
+    const baseURL = buildLoadmillLlmBaseUrl(loadmillBaseUrl);
+    if (!apiKey || !baseURL) {
+        throw new Error("Loadmill authentication is required for LLM access.");
+    }
+    return new OpenAI({
+        apiKey,
+        baseURL,
+        maxRetries,
+        fetch: createLoadmillGatewayFetch(),
+        defaultHeaders: {
+            "X-Loadmill-Client": clientName,
+        },
+    });
+}
+export function createFaraClient({ apiKey, baseUrl }) {
+    return new OpenAI({
+        apiKey: trimNullableString(apiKey) || "",
+        baseURL: trimNullableString(baseUrl) || DEFAULT_FARA_BASE_URL,
+    });
+}
+export function createResolvedLlmClient({ llmProviderMode = null, credentials = null, clientName = "desktop", maxRetries = 1, } = {}) {
+    const resolvedCredentials = resolveRuntimeCredentials(credentials);
+    const resolvedProviderMode = resolveLlmProviderMode(llmProviderMode);
+    if (resolvedProviderMode === "loadmill") {
+        if (!hasLoadmillLlmAccess(resolvedCredentials)) {
+            throw new Error(missingCredentialErrorMessage(resolvedProviderMode));
+        }
+        return createLlmClient({
+            loadmillApiToken: resolvedCredentials.loadmillApiToken,
+            loadmillBaseUrl: resolvedCredentials.loadmillBaseUrl,
+            clientName,
+            maxRetries,
+        });
+    }
+    if (!hasOpenAiLlmAccess(resolvedCredentials)) {
+        throw new Error(missingCredentialErrorMessage(resolvedProviderMode));
+    }
+    return createOpenAiClient(resolvedCredentials.openAiApiKey);
+}
 export function createRunContext({ config, credentials }) {
     const resolvedConfig = resolveRuntimeConfig(config);
     const resolvedCredentials = resolveRuntimeCredentials(credentials);
+    const resolvedProviderMode = resolveLlmProviderMode(resolvedConfig.llmProviderMode);
+    const effectiveConfig = {
+        ...resolvedConfig,
+        llmProviderMode: resolvedProviderMode,
+        cuaModel: resolveEffectiveCuaModel({
+            llmProviderMode: resolvedProviderMode,
+            cuaBackend: resolvedConfig.cuaBackend,
+            cuaModel: resolvedConfig.cuaModel,
+        }),
+    };
+    const effectiveCredentials = {
+        ...resolvedCredentials,
+    };
     return {
-        config: resolvedConfig,
-        credentials: resolvedCredentials,
+        config: effectiveConfig,
+        credentials: effectiveCredentials,
         clients: {
-            openai: createOpenAiClient(resolvedCredentials.openAiApiKey),
+            openai: createResolvedLlmClient({
+                llmProviderMode: resolvedProviderMode,
+                credentials: resolvedCredentials,
+                clientName: "desktop",
+            }),
+            fara: resolvedConfig.cuaBackend === "fara"
+                ? createFaraClient({
+                    apiKey: resolvedCredentials.faraApiKey,
+                    baseUrl: resolvedCredentials.faraBaseUrl,
+                })
+                : null,
         },
     };
 }

package/build/src/device/openai.js

@@ -1,10 +1,25 @@
 import { buildTestRevisionSystemPrompt } from "../prompts/editor.js";
-import { createOpenAiClient, resolveRuntimeConfig } from "../core/runtime-config.js";
+import { createOpenAiClient, LOADMILL_MODEL_ALIASES, resolveEffectiveHelperModel, resolveRuntimeConfig, } from "../core/runtime-config.js";
 import { DEFAULT_AIM_ASSIST_MODE } from "../core/aim-assist.js";
 import { DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD } from "../core/context-optimization.js";
 import { logger } from "../utils/logger.js";
 import { CuaDebugTracer } from "../utils/cua-debug-tracer.js";
 const cuaDebugTracer = new CuaDebugTracer(logger);
+function resolveOpenAiBaseUrl(client) {
+    return client?.baseURL || client?.baseUrl || client?._options?.baseURL || null;
+}
+function resolveOpenAiEndpointUrl(client, endpointPath) {
+    const baseURL = resolveOpenAiBaseUrl(client);
+    if (!baseURL) {
+        return null;
+    }
+    try {
+        return new URL(endpointPath.replace(/^\/+/, ''), `${String(baseURL).replace(/\/+$/, '')}/`).toString();
+    }
+    catch {
+        return `${String(baseURL).replace(/\/+$/, '')}/${endpointPath.replace(/^\/+/, '')}`;
+    }
+}
 function normalizeMessageContent(content) {
     if (Array.isArray(content)) {
         return content.map((item) => {
@@ -225,14 +240,15 @@ export function buildCuaRequestParams({ cuaModel, aimAssistMode = DEFAULT_AIM_AS
  * Revise a test script based on user feedback using simple chat completion
  * @param {{
  *   client: import("openai").default,
+ *   model?: string,
  *   originalScript: string,
  *   revisionRequest: string,
  * }} options
  * @returns {Promise<string>} - The revised test script
  */
-export async function reviseTestScript({ client, originalScript, revisionRequest }) {
+export async function reviseTestScript({ client, model = LOADMILL_MODEL_ALIASES.DEFAULT_AGENT_MODEL, originalScript, revisionRequest, }) {
     const response = await client.chat.completions.create({
-        model: "gpt-5.4",
+        model,
         messages: [{
                 role: "system",
                 content: buildTestRevisionSystemPrompt(originalScript, revisionRequest)
@@ -274,7 +290,14 @@ export async function sendCUARequest({ client, cuaModel, aimAssistMode = DEFAULT
         debugContext,
         previousResponseId
     });
+    trace.endpoint = {
+        baseURL: resolveOpenAiBaseUrl(client),
+        responsesURL: resolveOpenAiEndpointUrl(client, "responses"),
+        model: requestParams.model,
+        previousResponseId: requestParams.previous_response_id ?? null,
+    };
     logger.debug("CUA Request:", trace.requestLog);
+    logger.debug("CUA Request endpoint:", trace.endpoint);
     try {
         const response = await client.responses.create(requestParams);
         cuaDebugTracer.onResponse(trace, response);
@@ -311,6 +334,10 @@ export function createOpenAiExecutor({ client, config }) {
         async reviseTestScript(originalScript, revisionRequest) {
             return await reviseTestScript({
                 client: openAiClient,
+                model: resolveEffectiveHelperModel({
+                    llmProviderMode: runtimeConfig.llmProviderMode,
+                    cuaModel: runtimeConfig.cuaModel,
+                }),
                 originalScript,
                 revisionRequest,
             });

package/build/src/integrations/loadmill/executor.js

@@ -4,6 +4,7 @@
 import { createLoadmillApiClient } from "./client.js";
 import { interpretLoadmillCommand, selectBestFlow } from "./interpreter.js";
 import { extractLoadmillRuntimeParameters, renderLoadmillParameterContextNote, selectLoadmillParameterCandidates, } from "./parameters.js";
+import { LOADMILL_MODEL_ALIASES } from "../../core/runtime-config.js";
 import { logger } from "../../utils/logger.js";
 const POLL_INTERVAL_MS = 5000; // 5 seconds
 const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
@@ -62,7 +63,7 @@ async function selectRelevantParameterNames({ openAiClient, command, flowName, f
     }
     try {
         const response = await openAiClient.chat.completions.create({
-            model: "gpt-5.4",
+            model: LOADMILL_MODEL_ALIASES.DEFAULT_AGENT_MODEL,
             messages: buildParameterSelectionMessages({
                 command,
                 flowName,

package/build/src/integrations/loadmill/interpreter.js

@@ -1,6 +1,7 @@
 /**
  * AI-powered text interpretation for Loadmill commands
  */
+import { LOADMILL_MODEL_ALIASES } from "../../core/runtime-config.js";
 import { buildLoadmillCommandInterpretationMessages, buildLoadmillFlowSelectionMessages, } from "../../prompts/loadmill.js";
 /**
  * Interpret a natural language Loadmill command into structured data
@@ -9,7 +10,7 @@ import { buildLoadmillCommandInterpretationMessages, buildLoadmillFlowSelectionM
  */
 export async function interpretLoadmillCommand(userInput, { client }) {
     const response = await client.chat.completions.create({
-        model: "gpt-4o-mini",
+        model: LOADMILL_MODEL_ALIASES.FAST,
         messages: buildLoadmillCommandInterpretationMessages(userInput),
         response_format: { type: "json_object" }
     });
@@ -41,7 +42,7 @@ export async function selectBestFlow(flows, originalQuery, { client }) {
         return `${i + 1}. ID: ${f.id}, Name: "${name}"${suite ? `, Suite: "${suite}"` : ""}`;
     }).join("\n");
     const response = await client.chat.completions.create({
-        model: "gpt-4o-mini",
+        model: LOADMILL_MODEL_ALIASES.FAST,
         messages: buildLoadmillFlowSelectionMessages(originalQuery, flowList),
         response_format: { type: "json_object" }
     });

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

@@ -8,6 +8,31 @@ import { isAssertion } from "../device/assertions.js";
 import { logger } from "../utils/logger.js";
 import { emitDesktopDebug } from "../utils/desktop-debug.js";
 import { printCliOutput } from "../utils/console-output.js";
+// Mirrors the codes emitted by the Loadmill LLM gateway (see services/app/private/llm
+// in the server repo): a transient burst limit plus day/week/fixed-budget request and
+// token quotas. Free plans run on the fixed-budget quota.
+const LLM_USAGE_LIMIT_ERROR_CODES = new Set([
+    "llm_rate_limit_exceeded",
+    "llm_day_quota_exceeded",
+    "llm_week_quota_exceeded",
+    "llm_fixed_budget_quota_exceeded",
+    "llm_day_token_quota_exceeded",
+    "llm_week_token_quota_exceeded",
+    "llm_fixed_budget_token_quota_exceeded",
+]);
+const LOADMILL_UPGRADE_URL = "https://www.loadmill.com/book-a-demo";
+function isLlmUsageLimitError(err) {
+    if (!err || typeof err !== "object") {
+        return false;
+    }
+    if (typeof err.code === "string" && LLM_USAGE_LIMIT_ERROR_CODES.has(err.code)) {
+        return true;
+    }
+    return err.status === 429 && err.type === "rate_limit_error";
+}
+function getLlmUsageLimitMessage() {
+    return `Execution stopped: you've reached the AI usage limit for this account. Contact the Loadmill team to upgrade: ${LOADMILL_UPGRADE_URL}`;
+}
 /**
  * Execution Mode - Run test scripts line-by-line
  * Each instruction is executed in isolation (messages cleared after each turn)
@@ -267,6 +292,26 @@ export class ExecutionMode {
                 stack: err.stack
             });
             const addOutput = context.addOutput || printCliOutput;
+            if (isLlmUsageLimitError(err)) {
+                const stopMessage = getLlmUsageLimitMessage();
+                logger.debug('Stopping execution because an LLM usage limit was reached', {
+                    instruction,
+                    message: err.message,
+                    status: err.status,
+                    code: err.code,
+                    type: err.type,
+                });
+                this.emit(addOutput, 'error', stopMessage, context, stepContext, {
+                    eventType: 'error',
+                    payload: {
+                        message: stopMessage,
+                        status: err.status,
+                        code: err.code,
+                        type: err.type,
+                    }
+                });
+                return { success: false, error: stopMessage, usageLimitReached: true };
+            }
             // Check if we've exceeded max retries
             if (retryCount >= MAX_RETRIES) {
                 emitDesktopDebug("reconnect.attempt", "device", {

package/build/src/utils/cua-debug-tracer.js

@@ -23,6 +23,17 @@ function safeHeadersSnapshot(headers) {
     }
     return out;
 }
+function summarizeErrorCause(error) {
+    const cause = error?.cause;
+    if (!cause || typeof cause !== "object") {
+        return null;
+    }
+    return {
+        name: typeof cause.name === "string" ? cause.name : null,
+        message: typeof cause.message === "string" ? cause.message : String(cause),
+        code: typeof cause.code === "string" ? cause.code : null,
+    };
+}
 function summarizeContent(content) {
     if (typeof content === "string") {
         return truncateForDebug(content, 1600);
@@ -394,6 +405,7 @@ export class CuaDebugTracer {
             : null;
         const requestId = err?.request_id || responseError?.request_id || requestIdFromHeaders || null;
         const headers = safeHeadersSnapshot(err?.headers);
+        const provider = typeof responseError?.provider === "string" ? responseError.provider : null;
         emitDesktopDebug("device.error", "device", trace.ids, {
             localRequestId: trace.localRequestId,
             operation: "cua.request",
@@ -403,8 +415,11 @@ export class CuaDebugTracer {
             code: err?.code ?? responseError?.code ?? null,
             type: responseError?.type ?? null,
             param: responseError?.param ?? null,
+            provider,
             requestId,
             headers,
+            endpoint: trace.endpoint || null,
+            cause: summarizeErrorCause(err),
             chain: {
                 lastResponseId: trace.lastResponseMeta?.id ?? null,
                 lastResponseOutputTypes: trace.lastResponseMeta?.outputTypes ?? [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loadmill/droid-cua",
-  "version": "2.15.1",
+  "version": "2.16.0",
   "description": "AI-powered Android testing agent using OpenAI's computer-use model and ADB",
   "main": "build/index.js",
   "type": "module",
@@ -15,10 +15,11 @@
   ],
   "scripts": {
     "start": "tsx index.js",
-    "bench": "npm run bench:preflight && npm run bench:run && npm run bench:report",
+    "bench": "node scripts/benchmark.js",
     "bench:preflight": "node scripts/benchmark-preflight.js",
     "bench:run": "tsx index.js --platform android --instructions benchmarks/benchmark.dcua --context benchmarks/context.md --debug",
     "bench:report": "node scripts/benchmark-report.js",
+    "bench:report:web": "node scripts/benchmark-report-web.js",
     "execution:profile": "node scripts/execution-profile.js",
     "test": "node --test unit-tests/*.test.js",
     "build": "tsc",