@loadmill/droid-cua 2.5.0 → 2.7.0

package/LICENSE

@@ -1 +1 @@
-© 2025 Loadmill. All rights reserved.
+© 2026 Loadmill. All rights reserved.

package/README.md

@@ -155,7 +155,9 @@ Example headless config:
   },
   "appContextEnabled": true,
   "appContextBudget": 300,
-  "appContextPath": "../tests/context.md"
+  "appContextPath": "../tests/context.md",
+  "contextOptimizationEnabled": true,
+  "contextOptimizationThreshold": 30000
 }
 ```
 
@@ -177,10 +179,14 @@ Supported CLI options include:
 - `--context`
 - `--app-context-budget`
 - `--no-context`
+- `--context-optimization-threshold`
+- `--no-context-optimization`
 - `--base-prompt`
 - `--execution-prompt`
 - `--base-prompt-file`
 - `--execution-prompt-file`
+- `--strict`
+- `--no-strict`
 - `--record`
 - `--debug`
 
@@ -189,6 +195,9 @@ Config and precedence rules:
 - CLI flags override config file values.
 - `--context` overrides the config app-context path.
 - `--no-context` disables app context entirely.
+- Context Optimization is enabled by default with a `30000` input-token threshold.
+- `--context-optimization-threshold <tokens>` sets the threshold and enables Context Optimization.
+- `--no-context-optimization` disables Context Optimization.
 - `--base-prompt` and `--execution-prompt` let you pass prompt customizations inline on the command line.
 - `--base-prompt-file` and `--execution-prompt-file` override the corresponding prompt customizations from config.
 - If both inline and file-based prompt overrides are provided, the inline prompt flags win.
@@ -216,4 +225,4 @@ Current headless behavior is documented in [docs/headless-cli-spec.md](docs/head
 
 <h2 id="license">📄 License</h2>
 
-© 2025 Loadmill. All rights reserved.
+© 2026 Loadmill. All rights reserved.

package/build/index.js

@@ -1,7 +1,7 @@
 import minimist from "minimist";
 import dotenv from "dotenv";
 import path from "path";
-import { mkdir, readFile } from "fs/promises";
+import { mkdir } from "fs/promises";
 import { connectToDevice, getDeviceInfo } from "./src/device/connection.js";
 import { Session } from "./src/core/session.js";
 import { ExecutionEngine } from "./src/core/execution-engine.js";
@@ -11,10 +11,12 @@ import { ExecutionMode } from "./src/modes/execution-mode.js";
 import { logger } from "./src/utils/logger.js";
 import { selectDevice } from "./src/cli/device-selector.js";
 import { buildAppContextBriefing, DEFAULT_APP_CONTEXT_BUDGET } from "./src/core/app-context.js";
+import { CONTEXT_OPTIMIZATION_ENABLED_ENV, CONTEXT_OPTIMIZATION_THRESHOLD_ENV, } from "./src/core/context-optimization.js";
 import { resolveHeadlessExecutionConfig } from "./src/cli/headless-execution-config.js";
 import { printCliOutput } from "./src/utils/console-output.js";
 import { emitDesktopDebug } from "./src/utils/desktop-debug.js";
 import { createHeadlessDebugArtifacts } from "./src/cli/headless-debug.js";
+import { loadHeadlessInstructions } from "./src/cli/headless-instructions.js";
 dotenv.config();
 const args = minimist(process.argv.slice(2));
 let avdName = args["avd"];
@@ -74,14 +76,13 @@ async function main() {
                 console.log(`Debug logging enabled: ${currentLogFilePath}`);
             }
             console.log(`\nRunning test from: ${instructionsFile}\n`);
-            const content = await readFile(instructionsFile, "utf-8");
-            instructions = content
-                .split("\n")
-                .map(line => line.trim())
-                .filter(line => line.length > 0);
+            instructions = await loadHeadlessInstructions(instructionsFile);
             const taskText = instructions.join("\n");
             const headlessConfig = await resolveHeadlessExecutionConfig(args);
             process.env.OPENAI_CUA_MODEL = headlessConfig.cuaModel;
+            process.env[CONTEXT_OPTIMIZATION_ENABLED_ENV] = String(headlessConfig.contextOptimizationEnabled);
+            process.env[CONTEXT_OPTIMIZATION_THRESHOLD_ENV] = String(headlessConfig.contextOptimizationThreshold);
+            console.log(`Using CUA model: ${headlessConfig.cuaModel}`);
             let appContextBriefing = "";
             if (!headlessConfig.appContextEnabled) {
                 emitDesktopDebug("app_context.status", "execution", { runId }, {

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

@@ -1,7 +1,9 @@
 import path from "path";
 import { readFile } from "fs/promises";
 import { DEFAULT_APP_CONTEXT_BUDGET, MAX_APP_CONTEXT_BUDGET, MIN_APP_CONTEXT_BUDGET, } from "../core/app-context.js";
-const VALID_CUA_MODELS = new Set(["gpt-5.4", "computer-use-preview"]);
+import { DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD, MAX_CONTEXT_OPTIMIZATION_THRESHOLD, MIN_CONTEXT_OPTIMIZATION_THRESHOLD, } from "../core/context-optimization.js";
+const VALID_CUA_MODELS = new Set(["gpt-5.4", "gpt-5.4-mini", "computer-use-preview"]);
+const VALID_CUA_MODEL_LIST = ["gpt-5.4", "gpt-5.4-mini", "computer-use-preview"];
 function createEmptyPromptCustomizations() {
     return {
         basePromptInstructions: "",
@@ -19,10 +21,17 @@ function assertNonEmptyString(value, label) {
 }
 function validateCuaModel(value, label) {
     if (typeof value !== "string" || !VALID_CUA_MODELS.has(value)) {
-        throw new Error(`${label} must be one of: gpt-5.4, computer-use-preview.`);
+        throw new Error(`${label} must be one of: ${VALID_CUA_MODEL_LIST.join(", ")}.`);
     }
     return value;
 }
+function readEnvDefaultCuaModel() {
+    const rawValue = process.env.OPENAI_CUA_MODEL;
+    if (typeof rawValue !== "string" || rawValue.trim().length === 0) {
+        return "gpt-5.4";
+    }
+    return VALID_CUA_MODELS.has(rawValue) ? rawValue : "gpt-5.4";
+}
 function parseBooleanFlagState(args, key) {
     return {
         enabled: args[key] === true,
@@ -47,6 +56,24 @@ function parseBudgetValue(rawValue, label) {
     }
     return numericValue;
 }
+function parseContextOptimizationThreshold(rawValue, label) {
+    const numericValue = (() => {
+        if (typeof rawValue === "number") {
+            return rawValue;
+        }
+        if (typeof rawValue === "string" && /^-?\d+$/.test(rawValue.trim())) {
+            return Number.parseInt(rawValue, 10);
+        }
+        return Number.NaN;
+    })();
+    if (!Number.isInteger(numericValue)) {
+        throw new Error(`${label} must be an integer between ${MIN_CONTEXT_OPTIMIZATION_THRESHOLD} and ${MAX_CONTEXT_OPTIMIZATION_THRESHOLD}.`);
+    }
+    if (numericValue < MIN_CONTEXT_OPTIMIZATION_THRESHOLD || numericValue > MAX_CONTEXT_OPTIMIZATION_THRESHOLD) {
+        throw new Error(`${label} must be between ${MIN_CONTEXT_OPTIMIZATION_THRESHOLD} and ${MAX_CONTEXT_OPTIMIZATION_THRESHOLD}.`);
+    }
+    return numericValue;
+}
 function normalizePromptCustomizations(rawValue, label) {
     if (rawValue == null) {
         return createEmptyPromptCustomizations();
@@ -108,6 +135,8 @@ async function loadConfigFromFile(configPath) {
         appContextEnabled: undefined,
         appContextBudget: undefined,
         appContextPath: undefined,
+        contextOptimizationEnabled: undefined,
+        contextOptimizationThreshold: undefined,
         strictMode: undefined,
     };
     if ("cuaModel" in rawConfig) {
@@ -129,6 +158,15 @@ async function loadConfigFromFile(configPath) {
         assertNonEmptyString(rawConfig.appContextPath, "config.appContextPath");
         normalized.appContextPath = path.resolve(configDir, rawConfig.appContextPath);
     }
+    if ("contextOptimizationEnabled" in rawConfig) {
+        if (typeof rawConfig.contextOptimizationEnabled !== "boolean") {
+            throw new Error("config.contextOptimizationEnabled must be a boolean.");
+        }
+        normalized.contextOptimizationEnabled = rawConfig.contextOptimizationEnabled;
+    }
+    if ("contextOptimizationThreshold" in rawConfig) {
+        normalized.contextOptimizationThreshold = parseContextOptimizationThreshold(rawConfig.contextOptimizationThreshold, "config.contextOptimizationThreshold");
+    }
     if ("strictMode" in rawConfig) {
         if (typeof rawConfig.strictMode !== "boolean") {
             throw new Error("config.strictMode must be a boolean.");
@@ -142,6 +180,9 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     const configPath = typeof args.config === "string" ? args.config : null;
     const explicitContextPath = typeof args.context === "string" ? path.resolve(cwd, args.context) : null;
     const noContext = args["no-context"] === true || args.context === false;
+    const contextOptimizationEnabledByFlag = args["context-optimization"] === true;
+    const noContextOptimization = args["no-context-optimization"] === true || args["context-optimization"] === false;
+    const hasContextOptimizationThresholdFlag = args["context-optimization-threshold"] != null;
     const { enabled: strictEnabledByFlag, disabled: strictDisabledByFlag } = parseBooleanFlagState(args, "strict");
     const basePromptText = typeof args["base-prompt"] === "string" ? args["base-prompt"] : null;
     const executionPromptText = typeof args["execution-prompt"] === "string" ? args["execution-prompt"] : null;
@@ -153,6 +194,12 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     if (strictEnabledByFlag && strictDisabledByFlag) {
         throw new Error("--strict and --no-strict cannot be used together.");
     }
+    if (contextOptimizationEnabledByFlag) {
+        throw new Error("--context-optimization is not supported; Context Optimization is enabled by default.");
+    }
+    if (noContextOptimization && hasContextOptimizationThresholdFlag) {
+        throw new Error("--context-optimization-threshold and --no-context-optimization cannot be used together.");
+    }
     const fileConfig = configPath ? await loadConfigFromFile(configPath) : null;
     const promptCustomizations = {
         ...createEmptyPromptCustomizations(),
@@ -160,11 +207,13 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     };
     const resolved = {
         configPath: fileConfig?.configPath || null,
-        cuaModel: fileConfig?.cuaModel || "gpt-5.4",
+        cuaModel: fileConfig?.cuaModel || readEnvDefaultCuaModel(),
         promptCustomizations,
         appContextEnabled: fileConfig?.appContextEnabled ?? true,
         appContextBudget: fileConfig?.appContextBudget ?? DEFAULT_APP_CONTEXT_BUDGET,
         appContextPath: fileConfig?.appContextPath || null,
+        contextOptimizationEnabled: fileConfig?.contextOptimizationEnabled ?? true,
+        contextOptimizationThreshold: fileConfig?.contextOptimizationThreshold ?? DEFAULT_CONTEXT_OPTIMIZATION_THRESHOLD,
         strictMode: fileConfig?.strictMode ?? false,
     };
     if (typeof args["cua-model"] === "string") {
@@ -173,6 +222,10 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
     if (args["app-context-budget"] != null) {
         resolved.appContextBudget = parseBudgetValue(args["app-context-budget"], "--app-context-budget");
     }
+    if (hasContextOptimizationThresholdFlag) {
+        resolved.contextOptimizationEnabled = true;
+        resolved.contextOptimizationThreshold = parseContextOptimizationThreshold(args["context-optimization-threshold"], "--context-optimization-threshold");
+    }
     if (basePromptFilePath) {
         resolved.promptCustomizations.basePromptInstructions = await readTextFile(basePromptFilePath, "--base-prompt-file");
     }
@@ -193,6 +246,9 @@ export async function resolveHeadlessExecutionConfig(args, options = {}) {
         resolved.appContextEnabled = false;
         resolved.appContextPath = null;
     }
+    if (noContextOptimization) {
+        resolved.contextOptimizationEnabled = false;
+    }
     if (strictEnabledByFlag) {
         resolved.strictMode = true;
     }

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

@@ -0,0 +1,12 @@
+import { readFile } from "fs/promises";
+import { parseTestScript } from "../test-store/test-script.js";
+/**
+ * Load runnable instructions from a headless .dcua script file.
+ *
+ * @param {string} instructionsPath
+ * @returns {Promise<string[]>}
+ */
+export async function loadHeadlessInstructions(instructionsPath) {
+    const content = await readFile(instructionsPath, "utf-8");
+    return parseTestScript(content);
+}

package/build/src/commands/help.js

@@ -20,10 +20,12 @@ export async function handleHelp(args, session, context) {
     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: '  --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' });

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 };
+}