@loadmill/droid-cua 2.2.2 → 2.4.0

package/README.md

@@ -119,6 +119,11 @@ For CI, scripting, or advanced workflows, `droid-cua` also includes a CLI for ru
 
 Desktop projects can also keep run reports in a results folder, including JUnit XML output that the app can read back as project history.
 
+The recommended workflow is:
+- design and debug tests in the desktop app,
+- commit the `.dcua` file plus a headless CLI config file,
+- run the same test headlessly in CI with `--config` for prompt parity.
+
 Install:
 ```sh
 npm install -g @loadmill/droid-cua
@@ -134,15 +139,79 @@ droid-cua --avd adb:emulator-5554 --instructions tests/login.dcua
 
 # Headless iOS simulator run
 droid-cua --platform ios --avd "iPhone 16" --instructions tests/login.dcua
+
+# Headless run with prompt-parity config
+droid-cua --avd adb:emulator-5554 --instructions tests/login.dcua --config ci/droid-cua.json
+```
+
+Example headless config:
+```json
+{
+  "cuaModel": "gpt-5.4",
+  "promptCustomizations": {
+    "basePromptInstructions": "",
+    "designModeInstructions": "",
+    "executionModeInstructions": ""
+  },
+  "appContextEnabled": true,
+  "appContextBudget": 300,
+  "appContextPath": "../tests/context.md"
+}
+```
+
+Typical CI-style usage:
+```sh
+droid-cua \
+  --avd adb:emulator-5554 \
+  --instructions tests/login.dcua \
+  --config ci/droid-cua.json \
+  --debug
 ```
 
 Supported CLI options include:
 - `--avd`
 - `--platform`
 - `--instructions`
+- `--config`
+- `--cua-model`
+- `--context`
+- `--app-context-budget`
+- `--no-context`
+- `--base-prompt`
+- `--execution-prompt`
+- `--base-prompt-file`
+- `--execution-prompt-file`
 - `--record`
 - `--debug`
 
+Config and precedence rules:
+- Use `--config <file>` to supply prompt-affecting settings for headless runs.
+- CLI flags override config file values.
+- `--context` overrides the config app-context path.
+- `--no-context` disables app context entirely.
+- `--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.
+
+Example without a config file:
+```sh
+droid-cua \
+  --avd adb:emulator-5554 \
+  --instructions tests/login.dcua \
+  --context tests/context.md \
+  --base-prompt "stop and look at the screen after every action you take."
+```
+
+Headless debug artifacts:
+- `--debug` writes desktop-style structured JSONL artifacts under `logs/`.
+- Each run creates `logs/execution-<runId>-<timestamp>.jsonl`.
+- Each run also creates a sibling screenshot folder next to that JSONL file.
+- Shared device events are written to `logs/device-events.jsonl`.
+- `--debug` no longer creates the legacy `logs/debug-*.log` file for headless runs.
+- If `--debug` and `--record` are both used, screenshots are written to both the debug artifacts folder and the legacy `droid-cua-recording-<timestamp>` folder.
+
+Current headless behavior is documented in [docs/headless-cli-spec.md](docs/headless-cli-spec.md).
+
 ---
 
 <h2 id="license">📄 License</h2>

package/build/index.js

@@ -5,24 +5,43 @@ import { mkdir, readFile } 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";
-import { buildBaseSystemPrompt } from "./src/core/prompts.js";
+import { buildBaseSystemPrompt, buildExecutionModePrompt } from "./src/core/prompts.js";
 import { startInkShell } from "./src/cli/ink-shell.js";
 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 { 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";
 dotenv.config();
 const args = minimist(process.argv.slice(2));
 let avdName = args["avd"];
 let platform = args["platform"] || null; // 'ios' or 'android'
 const recordScreenshots = args["record"] || false;
 const instructionsFile = args.instructions || args.i || null;
+const appContextPath = typeof args.context === "string" ? args.context : null;
 const debugMode = args["debug"] || false;
-// Initialize debug logging
-await logger.init(debugMode);
+const strictFlag = args.strict === true;
+const noStrictFlag = args["no-strict"] === true || args.strict === false;
+if (strictFlag && noStrictFlag) {
+    throw new Error("--strict and --no-strict cannot be used together.");
+}
 const screenshotDir = path.join("droid-cua-recording-" + Date.now());
 if (recordScreenshots)
     await mkdir(screenshotDir, { recursive: true });
 async function main() {
+    const isHeadlessInstructionsRun = Boolean(instructionsFile);
+    const headlessDebug = createHeadlessDebugArtifacts({
+        cwd: process.cwd(),
+        enabled: isHeadlessInstructionsRun && debugMode
+    });
+    if (isHeadlessInstructionsRun && debugMode) {
+        await headlessDebug.init();
+    }
+    // Initialize legacy plain-text debug logging only for non-headless flows.
+    await logger.init(debugMode && !isHeadlessInstructionsRun);
     // If no device specified, show interactive selection menu
     if (!avdName && !platform) {
         const selection = await selectDevice();
@@ -38,31 +57,165 @@ async function main() {
     const session = new Session(deviceId, deviceInfo);
     const initialSystemText = buildBaseSystemPrompt(deviceInfo);
     session.setSystemPrompt(initialSystemText);
-    // Create execution engine
-    const engine = new ExecutionEngine(session, {
-        recordScreenshots,
-        screenshotDir,
-    });
     // If --instructions provided, run in headless mode
     if (instructionsFile) {
-        console.log(`\nRunning test from: ${instructionsFile}\n`);
-        // Read and parse the instructions file
-        const content = await readFile(instructionsFile, "utf-8");
-        const instructions = content
-            .split("\n")
-            .map(line => line.trim())
-            .filter(line => line.length > 0);
-        const executionMode = new ExecutionMode(session, engine, instructions, true); // true = headless mode
-        const result = await executionMode.execute();
-        if (result.success) {
-            process.exit(0);
+        const runId = `run-${Date.now()}`;
+        const testName = path.basename(instructionsFile);
+        let instructions = [];
+        let executionMode = null;
+        try {
+            await headlessDebug.startExecutionSession(runId, {
+                testName,
+                platform: deviceInfo.platform,
+                deviceName: deviceInfo.device_name
+            });
+            const currentLogFilePath = await headlessDebug.getCurrentLogFilePath();
+            if (currentLogFilePath) {
+                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);
+            const taskText = instructions.join("\n");
+            const headlessConfig = await resolveHeadlessExecutionConfig(args);
+            process.env.OPENAI_CUA_MODEL = headlessConfig.cuaModel;
+            let appContextBriefing = "";
+            if (!headlessConfig.appContextEnabled) {
+                emitDesktopDebug("app_context.status", "execution", { runId }, {
+                    source: "cli_context_flag",
+                    contextPath: null,
+                    budget: headlessConfig.appContextBudget,
+                    status: "disabled"
+                });
+            }
+            else if (headlessConfig.appContextPath) {
+                try {
+                    const result = await buildAppContextBriefing({
+                        contextPath: headlessConfig.appContextPath,
+                        taskText,
+                        budget: headlessConfig.appContextBudget,
+                    });
+                    appContextBriefing = result.briefing;
+                    emitDesktopDebug("app_context.status", "execution", { runId }, {
+                        source: "cli_context_flag",
+                        contextPath: result.contextPath,
+                        budget: headlessConfig.appContextBudget,
+                        outputTokens: result.outputTokens,
+                        status: appContextBriefing.trim().length > 0 ? "loaded" : "empty"
+                    });
+                    if (appContextBriefing) {
+                        emitDesktopDebug("app_context.briefing.full", "execution", { runId }, {
+                            source: "cli_context_flag",
+                            contextPath: result.contextPath,
+                            budget: headlessConfig.appContextBudget,
+                            outputTokens: result.outputTokens,
+                            briefing: appContextBriefing
+                        });
+                        console.log(`Using app context briefing from: ${result.contextPath}`);
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : "Unknown app context error";
+                    emitDesktopDebug("app_context.status", "execution", { runId }, {
+                        source: "cli_context_flag",
+                        contextPath: headlessConfig.appContextPath,
+                        budget: headlessConfig.appContextBudget,
+                        status: "failed",
+                        message
+                    });
+                    console.warn(`Warning: could not load app context from ${headlessConfig.appContextPath}. Running without briefing.`);
+                }
+            }
+            else {
+                emitDesktopDebug("app_context.status", "execution", { runId }, {
+                    source: "cli_context_flag",
+                    contextPath: null,
+                    budget: headlessConfig.appContextBudget,
+                    status: "missing"
+                });
+            }
+            const executionPrompt = buildExecutionModePrompt(deviceInfo, headlessConfig.promptCustomizations, appContextBriefing, { strictMode: headlessConfig.strictMode });
+            session.setSystemPrompt(executionPrompt);
+            const screenshotRecorder = headlessDebug.createExecutionScreenshotRecorder({
+                runId,
+                recordScreenshots,
+                screenshotDir
+            });
+            const engine = screenshotRecorder
+                ? new ExecutionEngine(session, {
+                    recordScreenshots: true,
+                    screenshotRecorder,
+                    strictMode: headlessConfig.strictMode
+                })
+                : new ExecutionEngine(session, {
+                    recordScreenshots,
+                    screenshotDir,
+                    strictMode: headlessConfig.strictMode
+                });
+            executionMode = new ExecutionMode(session, engine, instructions, true);
+            const result = await executionMode.execute({
+                runId,
+                addOutput: printCliOutput
+            });
+            const stats = executionMode.stats || {};
+            const durationMs = stats.startTime ? Math.max(0, Date.now() - stats.startTime) : 0;
+            await headlessDebug.endExecutionSession(runId, {
+                success: Boolean(result.success),
+                error: result.error ?? null,
+                durationMs,
+                instructionsTotal: instructions.length,
+                instructionsCompleted: stats.instructionsCompleted ?? 0,
+                actionsTotal: stats.actionCount ?? 0,
+                assertionsPassed: stats.assertionsPassed ?? 0,
+                assertionsFailed: stats.assertionsFailed ?? 0,
+                retries: stats.retryCount ?? 0
+            });
+            if (result.success) {
+                process.exit(0);
+            }
+            else {
+                console.error(`\nTest failed: ${result.error}`);
+                process.exit(1);
+            }
         }
-        else {
-            console.error(`\nTest failed: ${result.error}`);
-            process.exit(1);
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Failed to start execution.";
+            const stats = executionMode?.stats || {};
+            const durationMs = stats.startTime ? Math.max(0, Date.now() - stats.startTime) : 0;
+            await headlessDebug.endExecutionSession(runId, {
+                success: false,
+                error: message,
+                ...(stats.startTime
+                    ? {
+                        durationMs,
+                        instructionsTotal: instructions.length,
+                        instructionsCompleted: stats.instructionsCompleted ?? 0,
+                        actionsTotal: stats.actionCount ?? 0,
+                        assertionsPassed: stats.assertionsPassed ?? 0,
+                        assertionsFailed: stats.assertionsFailed ?? 0,
+                        retries: stats.retryCount ?? 0
+                    }
+                    : { reason: "start_failed" })
+            });
+            throw error;
         }
     }
+    const engine = new ExecutionEngine(session, {
+        recordScreenshots,
+        screenshotDir,
+        strictMode: strictFlag,
+    });
     // Otherwise, start interactive Ink shell
-    await startInkShell(session, engine);
+    await startInkShell(session, engine, {
+        appContextPath: appContextPath ? path.resolve(appContextPath) : null,
+        appContextBudget: DEFAULT_APP_CONTEXT_BUDGET,
+    });
 }
-main();
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`\nTest failed: ${message}`);
+    process.exit(1);
+});

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

@@ -0,0 +1,55 @@
+import path from "node:path";
+import { createStructuredDebugLogManager } from "../utils/structured-debug-log-manager.js";
+import { createCompositeScreenshotRecorder, createDebugScreenshotRecorder } from "../utils/run-screenshot-recorder.js";
+export function createHeadlessDebugArtifacts({ cwd = process.cwd(), enabled = false } = {}) {
+    const manager = createStructuredDebugLogManager({
+        enabled,
+        logsDirPath: path.join(cwd, "logs")
+    });
+    return {
+        async init() {
+            await manager.configure();
+            if (manager.isEnabled()) {
+                manager.installWorkspaceDebugBridge();
+                return await manager.getLogsDirPath();
+            }
+            return null;
+        },
+        isEnabled() {
+            return manager.isEnabled();
+        },
+        async startExecutionSession(runId, data = {}) {
+            await manager.startExecutionSession(runId, data);
+            return await manager.getCurrentLogFilePath();
+        },
+        async endExecutionSession(runId, data = {}) {
+            await manager.endExecutionSession(runId, data);
+        },
+        createExecutionScreenshotRecorder({ runId, recordScreenshots = false, screenshotDir = null }) {
+            const recorders = [];
+            const debugArtifactsDir = manager.getExecutionSessionArtifactsDir(runId);
+            if (debugArtifactsDir) {
+                recorders.push(createDebugScreenshotRecorder({ directoryPath: debugArtifactsDir }));
+            }
+            if (manager.isEnabled() && recordScreenshots && screenshotDir) {
+                recorders.push(createDebugScreenshotRecorder({ directoryPath: screenshotDir }));
+            }
+            if (recorders.length === 0) {
+                return null;
+            }
+            if (recorders.length === 1) {
+                return recorders[0];
+            }
+            return createCompositeScreenshotRecorder({ recorders });
+        },
+        getExecutionSessionArtifactsDir(runId) {
+            return manager.getExecutionSessionArtifactsDir(runId);
+        },
+        async getCurrentLogFilePath() {
+            return await manager.getCurrentLogFilePath();
+        },
+        async getLogsDirPath() {
+            return await manager.getLogsDirPath();
+        }
+    };
+}

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

@@ -0,0 +1,203 @@
+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"]);
+function createEmptyPromptCustomizations() {
+    return {
+        basePromptInstructions: "",
+        designModeInstructions: "",
+        executionModeInstructions: "",
+    };
+}
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function assertNonEmptyString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${label} must be a non-empty string.`);
+    }
+}
+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.`);
+    }
+    return value;
+}
+function parseBooleanFlagState(args, key) {
+    return {
+        enabled: args[key] === true,
+        disabled: args[`no-${key}`] === true || args[key] === false,
+    };
+}
+function parseBudgetValue(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_APP_CONTEXT_BUDGET} and ${MAX_APP_CONTEXT_BUDGET}.`);
+    }
+    if (numericValue < MIN_APP_CONTEXT_BUDGET || numericValue > MAX_APP_CONTEXT_BUDGET) {
+        throw new Error(`${label} must be between ${MIN_APP_CONTEXT_BUDGET} and ${MAX_APP_CONTEXT_BUDGET}.`);
+    }
+    return numericValue;
+}
+function normalizePromptCustomizations(rawValue, label) {
+    if (rawValue == null) {
+        return createEmptyPromptCustomizations();
+    }
+    if (!isPlainObject(rawValue)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    const normalized = createEmptyPromptCustomizations();
+    for (const key of Object.keys(normalized)) {
+        if (!(key in rawValue))
+            continue;
+        if (typeof rawValue[key] !== "string") {
+            throw new Error(`${label}.${key} must be a string.`);
+        }
+        normalized[key] = rawValue[key];
+    }
+    return normalized;
+}
+async function readJsonFile(filePath) {
+    const content = await readFile(filePath, "utf-8");
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Invalid JSON.";
+        throw new Error(`Could not parse config file ${filePath}: ${message}`);
+    }
+}
+async function readTextFile(filePath, label) {
+    try {
+        return await readFile(filePath, "utf-8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown file read error.";
+        throw new Error(`Could not read ${label} at ${filePath}: ${message}`);
+    }
+}
+async function loadConfigFromFile(configPath) {
+    const absoluteConfigPath = path.resolve(configPath);
+    let rawConfig;
+    try {
+        rawConfig = await readJsonFile(absoluteConfigPath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown config read error.";
+        if (message.startsWith("Could not parse config file ")) {
+            throw error;
+        }
+        throw new Error(`Could not read config file ${absoluteConfigPath}: ${message}`);
+    }
+    if (!isPlainObject(rawConfig)) {
+        throw new Error(`Config file ${absoluteConfigPath} must contain a JSON object.`);
+    }
+    const configDir = path.dirname(absoluteConfigPath);
+    const normalized = {
+        configPath: absoluteConfigPath,
+        cuaModel: undefined,
+        promptCustomizations: createEmptyPromptCustomizations(),
+        appContextEnabled: undefined,
+        appContextBudget: undefined,
+        appContextPath: undefined,
+        strictMode: undefined,
+    };
+    if ("cuaModel" in rawConfig) {
+        normalized.cuaModel = validateCuaModel(rawConfig.cuaModel, "config.cuaModel");
+    }
+    if ("promptCustomizations" in rawConfig) {
+        normalized.promptCustomizations = normalizePromptCustomizations(rawConfig.promptCustomizations, "config.promptCustomizations");
+    }
+    if ("appContextEnabled" in rawConfig) {
+        if (typeof rawConfig.appContextEnabled !== "boolean") {
+            throw new Error("config.appContextEnabled must be a boolean.");
+        }
+        normalized.appContextEnabled = rawConfig.appContextEnabled;
+    }
+    if ("appContextBudget" in rawConfig) {
+        normalized.appContextBudget = parseBudgetValue(rawConfig.appContextBudget, "config.appContextBudget");
+    }
+    if ("appContextPath" in rawConfig && rawConfig.appContextPath != null) {
+        assertNonEmptyString(rawConfig.appContextPath, "config.appContextPath");
+        normalized.appContextPath = path.resolve(configDir, rawConfig.appContextPath);
+    }
+    if ("strictMode" in rawConfig) {
+        if (typeof rawConfig.strictMode !== "boolean") {
+            throw new Error("config.strictMode must be a boolean.");
+        }
+        normalized.strictMode = rawConfig.strictMode;
+    }
+    return normalized;
+}
+export async function resolveHeadlessExecutionConfig(args, options = {}) {
+    const cwd = typeof options.cwd === "string" ? options.cwd : process.cwd();
+    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 { 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;
+    const basePromptFilePath = typeof args["base-prompt-file"] === "string" ? path.resolve(cwd, args["base-prompt-file"]) : null;
+    const executionPromptFilePath = typeof args["execution-prompt-file"] === "string" ? path.resolve(cwd, args["execution-prompt-file"]) : null;
+    if (explicitContextPath && noContext) {
+        throw new Error("--context and --no-context cannot be used together.");
+    }
+    if (strictEnabledByFlag && strictDisabledByFlag) {
+        throw new Error("--strict and --no-strict cannot be used together.");
+    }
+    const fileConfig = configPath ? await loadConfigFromFile(configPath) : null;
+    const promptCustomizations = {
+        ...createEmptyPromptCustomizations(),
+        ...(fileConfig?.promptCustomizations || {}),
+    };
+    const resolved = {
+        configPath: fileConfig?.configPath || null,
+        cuaModel: fileConfig?.cuaModel || "gpt-5.4",
+        promptCustomizations,
+        appContextEnabled: fileConfig?.appContextEnabled ?? true,
+        appContextBudget: fileConfig?.appContextBudget ?? DEFAULT_APP_CONTEXT_BUDGET,
+        appContextPath: fileConfig?.appContextPath || null,
+        strictMode: fileConfig?.strictMode ?? false,
+    };
+    if (typeof args["cua-model"] === "string") {
+        resolved.cuaModel = validateCuaModel(args["cua-model"], "--cua-model");
+    }
+    if (args["app-context-budget"] != null) {
+        resolved.appContextBudget = parseBudgetValue(args["app-context-budget"], "--app-context-budget");
+    }
+    if (basePromptFilePath) {
+        resolved.promptCustomizations.basePromptInstructions = await readTextFile(basePromptFilePath, "--base-prompt-file");
+    }
+    if (executionPromptFilePath) {
+        resolved.promptCustomizations.executionModeInstructions = await readTextFile(executionPromptFilePath, "--execution-prompt-file");
+    }
+    if (basePromptText !== null) {
+        resolved.promptCustomizations.basePromptInstructions = basePromptText;
+    }
+    if (executionPromptText !== null) {
+        resolved.promptCustomizations.executionModeInstructions = executionPromptText;
+    }
+    if (explicitContextPath) {
+        resolved.appContextEnabled = true;
+        resolved.appContextPath = explicitContextPath;
+    }
+    if (noContext) {
+        resolved.appContextEnabled = false;
+        resolved.appContextPath = null;
+    }
+    if (strictEnabledByFlag) {
+        resolved.strictMode = true;
+    }
+    else if (strictDisabledByFlag) {
+        resolved.strictMode = false;
+    }
+    return resolved;
+}

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

@@ -7,9 +7,10 @@ import { routeCommand } from '../commands/index.js';
  * Start the Ink-based conversational shell
  * @param {Object} session - Session object with device info
  * @param {Object} executionEngine - Execution engine instance
+ * @param {{ appContextPath?: string | null, appContextBudget?: number }} [options]
  * @returns {Promise<void>}
  */
-export async function startInkShell(session, executionEngine) {
+export async function startInkShell(session, executionEngine, options = {}) {
     let shouldExit = false;
     const handleInput = async (input, context) => {
         // Check if there's an active design mode - route input to it
@@ -29,7 +30,12 @@ export async function startInkShell(session, executionEngine) {
         }
         if (parsed.type === 'command') {
             // Route to command handler
-            const shouldContinue = await routeCommand(parsed.command, parsed.args, session, { ...context, engine: executionEngine });
+            const shouldContinue = await routeCommand(parsed.command, parsed.args, session, {
+                ...context,
+                engine: executionEngine,
+                appContextPath: options.appContextPath ?? null,
+                appContextBudget: options.appContextBudget
+            });
             if (!shouldContinue) {
                 shouldExit = true;
                 context.exit();

package/build/src/commands/help.js

@@ -19,8 +19,19 @@ export async function handleHelp(args, session, context) {
     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: '  --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: '  --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: '  --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' });
+    addOutput({ type: 'info', text: '  --execution-prompt-file Headless execution prompt customization file' });
+    addOutput({ type: 'info', text: '  --strict               Strict Mode: re-observe after the first action in a chain' });
+    addOutput({ type: 'info', text: '  --no-strict            Disable Strict Mode for headless config-driven runs' });
     addOutput({ type: 'info', text: '  --record               Record screenshots during execution' });
-    addOutput({ type: 'info', text: '  --debug                Enable debug logging' });
+    addOutput({ type: 'info', text: '  --debug                Enable structured JSONL debug artifacts' });
     addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Interactive commands:' });
     addOutput({ type: 'info', text: '  /help                    Show this help message' });
@@ -57,6 +68,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: '  droid-cua --avd avd:Pixel_8_API_35       (Launch Android AVD then connect)' });
     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: '  /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)' });