@loadmill/droid-cua 2.6.0 → 2.8.0

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

@@ -0,0 +1,196 @@
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, rm } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { emitDesktopDebug } from "../../utils/desktop-debug.js";
+import { requireInstalledBrowser } from "./installed-browser.js";
+import { clearActiveBrowserSession, getActiveBrowserSession, setActiveBrowserSession } from "./session-state.js";
+import { normalizeAutomationUrl, normalizeOptionalAutomationUrl } from "./url.js";
+const DEFAULT_VIEWPORT = { width: 1440, height: 900 };
+let browserConnectionTestHooks = null;
+function normalizeKnownPageUrl(url) {
+    if (typeof url !== "string" || url.trim().length === 0 || url.trim() === "about:blank") {
+        return null;
+    }
+    try {
+        return normalizeOptionalAutomationUrl(url);
+    }
+    catch {
+        return null;
+    }
+}
+function buildSessionBrowserInfo(url, installedBrowser) {
+    const currentUrl = normalizeKnownPageUrl(url);
+    const browserInfo = {
+        viewportWidth: DEFAULT_VIEWPORT.width,
+        viewportHeight: DEFAULT_VIEWPORT.height,
+        scaledWidth: DEFAULT_VIEWPORT.width,
+        scaledHeight: DEFAULT_VIEWPORT.height,
+        scale: 1,
+        platform: "browser",
+        browserName: installedBrowser?.browserName || "Browser",
+        browserFamily: installedBrowser?.browserFamily || null,
+        model: installedBrowser?.browserName || "Browser",
+    };
+    if (currentUrl) {
+        browserInfo.currentUrl = currentUrl;
+    }
+    return browserInfo;
+}
+function normalizeConnectOptions(targetOrOptions) {
+    if (typeof targetOrOptions === "string") {
+        return {
+            url: normalizeOptionalAutomationUrl(targetOrOptions),
+            headless: false,
+            sessionMode: "fresh",
+            persistentProfileDir: null,
+            freshProfileDir: null,
+        };
+    }
+    const options = targetOrOptions && typeof targetOrOptions === "object" ? targetOrOptions : {};
+    return {
+        url: normalizeOptionalAutomationUrl(options.url),
+        headless: options.headless === true,
+        sessionMode: options.sessionMode === "persistent" ? "persistent" : "fresh",
+        persistentProfileDir: typeof options.persistentProfileDir === "string" && options.persistentProfileDir.trim().length > 0
+            ? path.resolve(options.persistentProfileDir)
+            : null,
+        freshProfileDir: typeof options.freshProfileDir === "string" && options.freshProfileDir.trim().length > 0
+            ? path.resolve(options.freshProfileDir)
+            : null,
+    };
+}
+async function buildUserDataDir(options) {
+    if (options.sessionMode === "persistent") {
+        if (!options.persistentProfileDir) {
+            throw new Error("Persistent browser sessions require a profile directory.");
+        }
+        return {
+            userDataDir: options.persistentProfileDir,
+            cleanupOnDisconnect: false,
+        };
+    }
+    if (options.freshProfileDir) {
+        return {
+            userDataDir: options.freshProfileDir,
+            cleanupOnDisconnect: true,
+        };
+    }
+    return {
+        userDataDir: await mkdtemp(path.join(os.tmpdir(), "droid-cua-browser-profile-")),
+        cleanupOnDisconnect: true,
+    };
+}
+async function loadChromium() {
+    if (typeof browserConnectionTestHooks?.loadChromium === "function") {
+        return await browserConnectionTestHooks.loadChromium();
+    }
+    try {
+        const playwright = await import("playwright-core");
+        return playwright.chromium;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "playwright-core is unavailable";
+        throw new Error(`Browser automation requires the optional playwright-core dependency. Install project dependencies and try again. (${message})`);
+    }
+}
+async function resolveInstalledBrowserForLaunch() {
+    if (typeof browserConnectionTestHooks?.resolveInstalledBrowser === "function") {
+        return await browserConnectionTestHooks.resolveInstalledBrowser();
+    }
+    return await requireInstalledBrowser();
+}
+export async function connectToBrowser(targetOrOptions) {
+    const options = normalizeConnectOptions(targetOrOptions);
+    const installedBrowser = await resolveInstalledBrowserForLaunch();
+    const chromium = await loadChromium();
+    try {
+        getActiveBrowserSession();
+        await disconnect();
+    }
+    catch {
+        // no active session to close
+    }
+    const { userDataDir, cleanupOnDisconnect } = await buildUserDataDir(options);
+    const context = await chromium.launchPersistentContext(userDataDir, {
+        executablePath: installedBrowser.executablePath,
+        headless: options.headless,
+        viewport: DEFAULT_VIEWPORT,
+        screen: DEFAULT_VIEWPORT,
+        acceptDownloads: false,
+    });
+    const primaryPage = context.pages()[0] ?? (await context.newPage());
+    const sessionId = `browser-${randomUUID()}`;
+    const normalizedUrl = options.url;
+    context.on("page", (page) => {
+        if (page === primaryPage) {
+            return;
+        }
+        console.warn("New tab or popup opened. Automation will remain attached to the original page only.");
+        emitDesktopDebug("browser.popup", "device", { sessionId }, {
+            stage: "opened",
+            url: page.url() || null,
+        });
+    });
+    if (normalizedUrl) {
+        await primaryPage.goto(normalizedUrl, { waitUntil: "load" });
+    }
+    setActiveBrowserSession({
+        sessionId,
+        context,
+        page: primaryPage,
+        url: normalizedUrl,
+        sessionMode: options.sessionMode,
+        userDataDir,
+        cleanupOnDisconnect,
+        installedBrowser,
+    });
+    emitDesktopDebug("browser.connect", "device", {}, {
+        platform: "browser",
+        stage: "success",
+        browserSessionId: sessionId,
+        browserFamily: installedBrowser.browserFamily,
+        browserName: installedBrowser.browserName,
+        url: normalizedUrl ?? undefined,
+        sessionMode: options.sessionMode,
+    });
+    return sessionId;
+}
+export async function getBrowserInfo(browserSessionId) {
+    const session = getActiveBrowserSession(browserSessionId);
+    const currentUrl = normalizeKnownPageUrl(session.page.url()) || session.url || null;
+    return buildSessionBrowserInfo(currentUrl, session.installedBrowser);
+}
+export async function getScreenshotAsBase64(browserSessionId) {
+    const session = getActiveBrowserSession(browserSessionId);
+    const imageBuffer = await session.page.screenshot({ type: "png" });
+    return imageBuffer.toString("base64");
+}
+export async function navigateToUrl(browserSessionId, url) {
+    const session = getActiveBrowserSession(browserSessionId);
+    const normalizedUrl = normalizeAutomationUrl(url);
+    await session.page.goto(normalizedUrl, { waitUntil: "load" });
+    session.url = normalizedUrl;
+    emitDesktopDebug("browser.navigate", "device", { browserSessionId }, {
+        platform: "browser",
+        url: normalizedUrl,
+    });
+    return normalizedUrl;
+}
+export async function disconnect() {
+    let session;
+    try {
+        session = getActiveBrowserSession();
+    }
+    catch {
+        return;
+    }
+    clearActiveBrowserSession();
+    await session.context.close();
+    if (session.cleanupOnDisconnect) {
+        await rm(session.userDataDir, { recursive: true, force: true });
+    }
+}
+export function __setBrowserConnectionTestHooks(hooks = null) {
+    browserConnectionTestHooks = hooks;
+}

package/build/src/browser/playwright/installed-browser.js

@@ -0,0 +1,131 @@
+import os from "node:os";
+import path from "node:path";
+import { access } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+export const CHROME_INSTALL_URL = "https://www.google.com/chrome/";
+export const EDGE_INSTALL_URL = "https://www.microsoft.com/edge/download";
+function readEnvValue(env, ...keys) {
+    for (const key of keys) {
+        const value = env?.[key];
+        if (typeof value === "string" && value.trim()) {
+            return value.trim();
+        }
+    }
+    return null;
+}
+function normalizeWindowsBaseDirs(env, homeDir) {
+    const programFiles = readEnvValue(env, "PROGRAMFILES", "ProgramFiles") || "C:\\Program Files";
+    const programFilesX86 = readEnvValue(env, "PROGRAMFILES(X86)") || "C:\\Program Files (x86)";
+    const localAppData = readEnvValue(env, "LOCALAPPDATA")
+        || (homeDir ? path.join(homeDir, "AppData", "Local") : null)
+        || "C:\\Users\\Default\\AppData\\Local";
+    return { programFiles, programFilesX86, localAppData };
+}
+function uniquePaths(paths = []) {
+    return [...new Set(paths.filter((value) => typeof value === "string" && value.trim().length > 0))];
+}
+export function listInstalledBrowserCandidates({ platform = process.platform, env = process.env, homeDir = os.homedir(), } = {}) {
+    if (platform === "darwin") {
+        const appRoots = uniquePaths([
+            "/Applications",
+            homeDir ? path.join(homeDir, "Applications") : null,
+        ]);
+        return [
+            {
+                browserFamily: "chrome",
+                browserName: "Google Chrome",
+                candidates: appRoots.map((root) => path.join(root, "Google Chrome.app", "Contents", "MacOS", "Google Chrome")),
+            },
+            {
+                browserFamily: "edge",
+                browserName: "Microsoft Edge",
+                candidates: appRoots.map((root) => path.join(root, "Microsoft Edge.app", "Contents", "MacOS", "Microsoft Edge")),
+            },
+        ];
+    }
+    if (platform === "win32") {
+        const { programFiles, programFilesX86, localAppData } = normalizeWindowsBaseDirs(env, homeDir);
+        return [
+            {
+                browserFamily: "chrome",
+                browserName: "Google Chrome",
+                candidates: uniquePaths([
+                    path.win32.join(programFiles, "Google", "Chrome", "Application", "chrome.exe"),
+                    path.win32.join(programFilesX86, "Google", "Chrome", "Application", "chrome.exe"),
+                    path.win32.join(localAppData, "Google", "Chrome", "Application", "chrome.exe"),
+                ]),
+            },
+            {
+                browserFamily: "edge",
+                browserName: "Microsoft Edge",
+                candidates: uniquePaths([
+                    path.win32.join(programFiles, "Microsoft", "Edge", "Application", "msedge.exe"),
+                    path.win32.join(programFilesX86, "Microsoft", "Edge", "Application", "msedge.exe"),
+                    path.win32.join(localAppData, "Microsoft", "Edge", "Application", "msedge.exe"),
+                ]),
+            },
+        ];
+    }
+    return [];
+}
+async function pathExistsAndIsRunnable(filePath, platform, accessFn) {
+    const accessMode = platform === "win32" ? fsConstants.F_OK : fsConstants.X_OK;
+    try {
+        await accessFn(filePath, accessMode);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function buildMissingBrowserMessage(platform) {
+    if (platform !== "darwin" && platform !== "win32") {
+        return "Installed browser detection is currently supported only on macOS and Windows. Install Google Chrome or Microsoft Edge on a supported machine.";
+    }
+    return `No supported browser was found. Install Google Chrome or Microsoft Edge and try again. Chrome: ${CHROME_INSTALL_URL} Edge: ${EDGE_INSTALL_URL}`;
+}
+export async function resolveInstalledBrowser({ platform = process.platform, env = process.env, homeDir = os.homedir(), accessFn = access, } = {}) {
+    const browserGroups = listInstalledBrowserCandidates({ platform, env, homeDir });
+    for (const browser of browserGroups) {
+        for (const executablePath of browser.candidates) {
+            if (await pathExistsAndIsRunnable(executablePath, platform, accessFn)) {
+                return {
+                    browserFamily: browser.browserFamily,
+                    browserName: browser.browserName,
+                    executablePath,
+                };
+            }
+        }
+    }
+    return null;
+}
+export async function getInstalledBrowserAvailability(options = {}) {
+    const resolved = await resolveInstalledBrowser(options);
+    if (!resolved) {
+        return {
+            available: false,
+            browserFamily: null,
+            browserName: null,
+            executablePath: null,
+            message: buildMissingBrowserMessage(options.platform ?? process.platform),
+        };
+    }
+    return {
+        available: true,
+        browserFamily: resolved.browserFamily,
+        browserName: resolved.browserName,
+        executablePath: resolved.executablePath,
+        message: null,
+    };
+}
+export async function requireInstalledBrowser(options = {}) {
+    const availability = await getInstalledBrowserAvailability(options);
+    if (!availability.available || !availability.browserName || !availability.executablePath) {
+        throw new Error(availability.message || buildMissingBrowserMessage(options.platform ?? process.platform));
+    }
+    return {
+        browserFamily: availability.browserFamily,
+        browserName: availability.browserName,
+        executablePath: availability.executablePath,
+    };
+}

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

@@ -0,0 +1,19 @@
+let activeSession = null;
+export function setActiveBrowserSession(session) {
+    activeSession = session;
+}
+export function clearActiveBrowserSession() {
+    activeSession = null;
+}
+export function getActiveBrowserSession(browserSessionId = null) {
+    if (!activeSession) {
+        throw new Error("Not connected to a browser session. Call connectToBrowser first.");
+    }
+    if (browserSessionId && activeSession.sessionId !== browserSessionId) {
+        throw new Error("Requested browser session is no longer active.");
+    }
+    return activeSession;
+}
+export function getActiveBrowserPage(browserSessionId = null) {
+    return getActiveBrowserSession(browserSessionId).page;
+}

package/build/src/browser/playwright/url.js

@@ -0,0 +1,79 @@
+const HTTP_SCHEME_RE = /^https?:\/\//i;
+const SCHEME_RE = /^[a-z][a-z\d+\-.]*:\/\//i;
+const LOCAL_HOST_RE = /^(localhost|127\.0\.0\.1)(:\d+)?$/i;
+const EXPLICIT_PORT_RE = /^[^/]+:\d+$/;
+const URL_ERROR_MESSAGE = "Browser URL must be a valid host or http:// / https:// URL.";
+function hasUnsupportedBareScheme(rawValue) {
+    if (rawValue.includes("://")) {
+        return false;
+    }
+    const authority = rawValue.split(/[/?#]/, 1)[0]?.trim() || "";
+    const colonIndex = authority.indexOf(":");
+    if (colonIndex <= 0 || LOCAL_HOST_RE.test(authority) || EXPLICIT_PORT_RE.test(authority)) {
+        return false;
+    }
+    const prefix = authority.slice(0, colonIndex);
+    const suffix = authority.slice(colonIndex + 1);
+    return /^[a-z][a-z\d+\-.]*$/i.test(prefix) && !prefix.includes(".") && !/^\d+$/.test(suffix);
+}
+function inferDefaultScheme(rawValue) {
+    const authority = rawValue.split(/[/?#]/, 1)[0]?.trim() || "";
+    if (LOCAL_HOST_RE.test(authority) || EXPLICIT_PORT_RE.test(authority)) {
+        return "http://";
+    }
+    return "https://";
+}
+function parseUrlCandidate(rawValue) {
+    if (rawValue == null) {
+        return null;
+    }
+    if (typeof rawValue !== "string") {
+        throw new Error("Browser URL must be a string.");
+    }
+    const trimmed = rawValue.trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (hasUnsupportedBareScheme(trimmed)) {
+        throw new Error("Browser URL must use http:// or https://.");
+    }
+    if (SCHEME_RE.test(trimmed) && !HTTP_SCHEME_RE.test(trimmed)) {
+        throw new Error("Browser URL must use http:// or https://.");
+    }
+    const candidate = HTTP_SCHEME_RE.test(trimmed)
+        ? trimmed
+        : `${inferDefaultScheme(trimmed)}${trimmed}`;
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(candidate);
+    }
+    catch {
+        throw new Error(URL_ERROR_MESSAGE);
+    }
+    if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+        throw new Error("Browser URL must use http:// or https://.");
+    }
+    if (!parsedUrl.hostname) {
+        throw new Error(URL_ERROR_MESSAGE);
+    }
+    return parsedUrl;
+}
+export function normalizeOptionalAutomationUrl(rawValue) {
+    const parsedUrl = parseUrlCandidate(rawValue);
+    return parsedUrl ? parsedUrl.toString() : null;
+}
+export function normalizeAutomationUrl(rawValue) {
+    const normalizedUrl = normalizeOptionalAutomationUrl(rawValue);
+    if (!normalizedUrl) {
+        throw new Error("Browser URL is required.");
+    }
+    return normalizedUrl;
+}
+export function formatAutomationDisplayName(rawUrl) {
+    const normalizedUrl = normalizeOptionalAutomationUrl(rawUrl);
+    if (!normalizedUrl) {
+        return "Browser";
+    }
+    const parsedUrl = new URL(normalizedUrl);
+    return parsedUrl.host || parsedUrl.origin || normalizedUrl;
+}

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/cli/headless-target.js

@@ -0,0 +1,64 @@
+function normalizeTarget(value) {
+    if (value == null || value === "") {
+        return "mobile";
+    }
+    if (typeof value !== "string") {
+        throw new Error("--target must be one of: mobile, web.");
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "mobile" || normalized === "web") {
+        return normalized;
+    }
+    throw new Error("--target must be one of: mobile, web.");
+}
+function normalizeSessionMode(value) {
+    if (value == null || value === "") {
+        return "persistent";
+    }
+    if (typeof value !== "string") {
+        throw new Error("--session-mode must be one of: persistent, fresh.");
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "persistent" || normalized === "fresh") {
+        return normalized;
+    }
+    throw new Error("--session-mode must be one of: persistent, fresh.");
+}
+function hasNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+export function resolveHeadlessTarget(args = {}) {
+    const target = normalizeTarget(args.target);
+    const sessionMode = normalizeSessionMode(args["session-mode"]);
+    const url = hasNonEmptyString(args.url) ? args.url.trim() : null;
+    const avdName = hasNonEmptyString(args.avd) ? args.avd.trim() : null;
+    const platform = hasNonEmptyString(args.platform) ? args.platform.trim() : null;
+    if (target === "web") {
+        if (!url) {
+            throw new Error("--target web requires --url.");
+        }
+        if (avdName || platform) {
+            throw new Error("--avd and --platform cannot be used with --target web.");
+        }
+        return {
+            target,
+            url,
+            sessionMode,
+            avdName: null,
+            platform: null,
+        };
+    }
+    if (hasNonEmptyString(args.url)) {
+        throw new Error("--url can only be used with --target web.");
+    }
+    if (args["session-mode"] != null) {
+        throw new Error("--session-mode can only be used with --target web.");
+    }
+    return {
+        target,
+        url: null,
+        sessionMode: null,
+        avdName,
+        platform,
+    };
+}