@loadmill/droid-cua 2.3.0 → 2.4.0

package/build/src/device/openai.js

@@ -1,4 +1,6 @@
 import OpenAI from "openai";
+import { buildTestRevisionSystemPrompt } from "../prompts/editor.js";
+import { buildAppContextCompactionInput } from "../prompts/execution.js";
 import { logger } from "../utils/logger.js";
 import { CuaDebugTracer } from "../utils/cua-debug-tracer.js";
 let openai = null;
@@ -129,23 +131,7 @@ export async function reviseTestScript(originalScript, revisionRequest) {
         model: "gpt-4o",
         messages: [{
                 role: "system",
-                content: `You are editing a test script based on user feedback.
-
-Current test script:
-${originalScript}
-
-User's revision request:
-${revisionRequest}
-
-Apply the user's changes and output the revised test script.
-
-FORMAT RULES:
-- One simple instruction per line (NO numbers, NO bullets)
-- Use imperative commands: "Open X", "Click Y", "Type Z"
-- Include "assert: <condition>" lines to validate expected behavior
-- End with "exit"
-
-Output only the revised test script, nothing else.`
+                content: buildTestRevisionSystemPrompt(originalScript, revisionRequest)
             }]
     });
     return response.choices[0].message.content.trim();
@@ -154,102 +140,11 @@ export async function compactAppContext({ contextDocument, taskDescription, toke
     const response = await getOpenAI().responses.create({
         model: "gpt-5.4",
         temperature: 0,
-        input: [
-            {
-                role: "system",
-                content: [{
-                        type: "input_text",
-                        text: `You are compressing an app context document for a mobile testing agent.
-
-You will receive:
-1. A context document
-2. A test task
-
-Your job is to SELECT only the facts from the context document that are useful for the given task.
-The output will be injected into a system prompt with a strict token budget.
-
-CRITICAL:
-- Use only facts explicitly supported by the context document
-- Never invent, infer, normalize, substitute, or improve credentials, labels, screen names, button names, or numeric values
-- Preserve exact values verbatim when present in the source
-- Prefer facts that help the agent act correctly when they are not obvious from the task alone
-- Do not restate, paraphrase, summarize, or reorganize the test task
-- The output must not read like instructions or a test plan
-- Do not describe what the agent should do
-- Output only reference knowledge about the app
-- If a line could be copied from the task with minor wording changes, omit it
-- Prefer copying source facts verbatim or near-verbatim over rewriting them
-- Do not collapse multiple specific source facts into one generic summary if that removes useful distinctions
-
-Selection priority:
-1. Facts the agent would NOT know from the test script alone
-2. Facts that are hard to infer from screenshots
-3. Non-obvious navigation or interaction details
-4. Exact visible labels needed to act correctly
-5. Credentials and other exact values
-
-High-value facts:
-- exact UI labels
-- how state, mode, or account selection is performed
-- where logout is located
-- hidden or non-obvious navigation
-- which menu items are decorative or non-functional
-- screen titles and section labels used to confirm location
-- exact credentials and role labels
-
-Low-value facts:
-- restating the test steps
-- repeating literal values already present in the task
-- generic summaries like "approve the transaction"
-
-When the task involves authentication, switching state or mode, opening menus, or moving between major areas of the app, strongly prefer including:
-- how account, state, or mode selection is performed
-- exact visible labels for the relevant controls
-- where exit or sign-out actions are located
-- the screen or section labels that confirm the agent is in the right place
-
-Rules:
-- Output plain text only
-- No markdown, no bullet symbols, no numbering, no headers
-- Use terse, factual language: one fact per line, no filler words
-- Blank lines only to separate logical groups
-- Prefer exact visible UI labels over summaries
-- Do not describe step-by-step procedures
-- Do not restate the test workflow
-- State only facts about screens, elements, hidden interactions, entities, credentials, and navigation
-- If a useful fact is not explicitly stated in the context document, omit it
-- Include only information relevant to this task
-- Do not waste space repeating the task itself
-- If the task already states a value or action, include it only when the context adds non-obvious execution details
-- Return a short result or an empty string if little is relevant
-- Target: under ${tokenBudget} tokens
-
-Bad output patterns to avoid:
-- generic summaries that remove actionable details
-- lines that restate the task in generic prose
-- lines that describe obvious workflow steps instead of app knowledge
-- lines that replace exact source labels or mechanisms with broad summaries
-
-Good output characteristics:
-- preserves the exact label or mechanism from the source when it matters
-- keeps distinctions like dropdown vs tabs, drawer vs visible button, exact section titles, exact button text
-- includes hidden or non-obvious navigation details when relevant
-
-Return only the briefing text.`
-                    }]
-            },
-            {
-                role: "user",
-                content: [{
-                        type: "input_text",
-                        text: `APP CONTEXT DOCUMENT:
-${contextDocument}
-
-TASK:
-${taskDescription}`
-                    }]
-            }
-        ]
+        input: buildAppContextCompactionInput({
+            contextDocument,
+            taskDescription,
+            tokenBudget,
+        })
     });
     return {
         briefing: typeof response.output_text === "string" ? response.output_text.trim() : "",

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

@@ -2,6 +2,7 @@
  * AI-powered text interpretation for Loadmill commands
  */
 import OpenAI from "openai";
+import { buildLoadmillCommandInterpretationMessages, buildLoadmillFlowSelectionMessages, } from "../../prompts/loadmill.js";
 let openai = null;
 function getOpenAI() {
     if (!openai) {
@@ -19,39 +20,7 @@ function getOpenAI() {
 export async function interpretLoadmillCommand(userInput) {
     const response = await getOpenAI().chat.completions.create({
         model: "gpt-4o-mini",
-        messages: [
-            {
-                role: "system",
-                content: `You are a parser that extracts structured data from natural language Loadmill commands.
-
-Extract the following from the user's input:
-1. searchQuery: The flow name or description to search for (required). FIX any obvious typos or misspellings.
-2. parameters: Any key=value pairs mentioned (as an object)
-3. action: Either "run" (if user wants to execute) or "search" (if user just wants to find flows)
-
-Output JSON only, no markdown or explanation.
-
-Examples:
-Input: "run the checkout flow with user=test123"
-Output: {"searchQuery": "checkout flow", "parameters": {"user": "test123"}, "action": "run"}
-
-Input: "search for login test"
-Output: {"searchQuery": "login test", "parameters": {}, "action": "search"}
-
-Input: "run user authentication with email=test@example.com password=secret123"
-Output: {"searchQuery": "user authentication", "parameters": {"email": "test@example.com", "password": "secret123"}, "action": "run"}
-
-Input: "execute payment flow"
-Output: {"searchQuery": "payment flow", "parameters": {}, "action": "run"}
-
-Input: "create a transction with amount=200"
-Output: {"searchQuery": "transaction", "parameters": {"amount": "200"}, "action": "run"}`
-            },
-            {
-                role: "user",
-                content: userInput
-            }
-        ],
+        messages: buildLoadmillCommandInterpretationMessages(userInput),
         response_format: { type: "json_object" }
     });
     const content = response.choices[0].message.content;
@@ -84,29 +53,7 @@ export async function selectBestFlow(flows, originalQuery) {
     }).join("\n");
     const response = await getOpenAI().chat.completions.create({
         model: "gpt-4o-mini",
-        messages: [
-            {
-                role: "system",
-                content: `You are selecting the best matching test flow based on a user query.
-
-Given the user's query and a list of available flows, select the best match.
-
-Output JSON with:
-- index: 1-based index of the best matching flow
-- confidence: number between 0 and 1 indicating how confident you are
-
-If no flow seems to match well, set confidence to a low value (< 0.5).
-
-Output JSON only, no markdown.`
-            },
-            {
-                role: "user",
-                content: `Query: "${originalQuery}"
-
-Available flows:
-${flowList}`
-            }
-        ],
+        messages: buildLoadmillFlowSelectionMessages(originalQuery, flowList),
         response_format: { type: "json_object" }
     });
     const content = response.choices[0].message.content;

package/build/src/modes/design-mode-ink.js

@@ -1,6 +1,6 @@
 import { getScreenshotAsBase64 } from "../device/connection.js";
 import { sendCUARequest, reviseTestScript } from "../device/openai.js";
-import { buildDesignModePrompt } from "../core/prompts.js";
+import { buildDesignModePrompt, buildDesignRecoveryPrompt } from "../core/prompts.js";
 import { saveTest } from "../test-store/test-manager.js";
 import { logger } from "../utils/logger.js";
 /**
@@ -20,6 +20,7 @@ export class DesignModeInk {
         this.waitingForInput = false; // Flag to indicate we're explicitly waiting for input
         this.inputResolver = null; // Promise resolver for input
         this.initialUserPrompt = null; // Store initial prompt for error recovery
+        this.baseDesignPrompt = null;
         this.consecutiveErrorCount = 0;
         this.maxConsecutiveErrors = 3;
     }
@@ -30,7 +31,10 @@ export class DesignModeInk {
     async start() {
         const addOutput = this.context.addOutput;
         // Set design mode system prompt
-        const designPrompt = buildDesignModePrompt(this.session.deviceInfo);
+        const designPrompt = buildDesignModePrompt(this.session.deviceInfo, {}, {
+            strictMode: Boolean(this.engine?.strictMode)
+        });
+        this.baseDesignPrompt = designPrompt;
         this.session.setSystemPrompt(designPrompt);
         // Update UI
         if (this.context.setMode) {
@@ -330,21 +334,12 @@ export class DesignModeInk {
                 }
                 // Automatic recovery - continue from where we left off using transcript
                 addOutput({ type: 'info', text: 'Recovering from error and continuing...' });
-                // Build recovery context with transcript
-                const designPrompt = buildDesignModePrompt(this.session.deviceInfo);
-                const recoveryContext = `${designPrompt}
-
-RECOVERY MODE:
-The previous session encountered an error and was interrupted. Here is everything that happened so far:
-
-${this.session.getTranscriptText()}
-
-Continue from where we left off and complete the original task: "${this.initialUserPrompt}"
-
-Remember:
-- Don't repeat actions that already succeeded
-- Continue towards generating the test script
-- If the flow was complete before the error, generate the script now`;
+                const recoveryContext = buildDesignRecoveryPrompt({
+                    basePrompt: this.baseDesignPrompt || this.session.systemPrompt || buildDesignModePrompt(this.session.deviceInfo),
+                    transcript: this.session.getTranscriptText(),
+                    objective: this.initialUserPrompt,
+                    errorMessage: err.message
+                });
                 // Reset conversation state for fresh API call
                 this.session.clearMessages();
                 this.session.addMessage("system", recoveryContext);

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

@@ -1,7 +1,7 @@
 import readline from "readline";
 import { getScreenshotAsBase64 } from "../device/connection.js";
 import { sendCUARequest, reviseTestScript } from "../device/openai.js";
-import { buildDesignModePrompt } from "../core/prompts.js";
+import { buildDesignModePrompt, buildDesignRecoveryPrompt } from "../core/prompts.js";
 import { saveTest } from "../test-store/test-manager.js";
 import { logger } from "../utils/logger.js";
 /**
@@ -17,6 +17,7 @@ export class DesignMode {
         this.escPressed = false;
         this.recentActions = []; // Track recent actions for stuck detection
         this.initialUserPrompt = null; // Store initial prompt for error recovery
+        this.baseDesignPrompt = null;
         this.consecutiveErrorCount = 0;
         this.maxConsecutiveErrors = 3;
     }
@@ -27,7 +28,10 @@ export class DesignMode {
      */
     async start(context) {
         // Set design mode system prompt
-        const designPrompt = buildDesignModePrompt(this.session.deviceInfo);
+        const designPrompt = buildDesignModePrompt(this.session.deviceInfo, {}, {
+            strictMode: Boolean(this.engine?.strictMode)
+        });
+        this.baseDesignPrompt = designPrompt;
         this.session.setSystemPrompt(designPrompt);
         console.log(`\n=== Design Mode: Creating test "${this.testName}" ===`);
         console.log("Describe what you want to test. The agent will explore autonomously.");
@@ -314,21 +318,12 @@ export class DesignMode {
                 }
                 // Automatic recovery - continue from where we left off using transcript
                 console.log("\nRecovering from error and continuing...");
-                // Build recovery context with transcript
-                const designPrompt = buildDesignModePrompt(this.session.deviceInfo);
-                const recoveryContext = `${designPrompt}
-
-RECOVERY MODE:
-The previous session encountered an error and was interrupted. Here is everything that happened so far:
-
-${this.session.getTranscriptText()}
-
-Continue from where we left off and complete the original task: "${this.initialUserPrompt}"
-
-Remember:
-- Don't repeat actions that already succeeded
-- Continue towards generating the test script
-- If the flow was complete before the error, generate the script now`;
+                const recoveryContext = buildDesignRecoveryPrompt({
+                    basePrompt: this.baseDesignPrompt || this.session.systemPrompt || buildDesignModePrompt(this.session.deviceInfo),
+                    transcript: this.session.getTranscriptText(),
+                    objective: this.initialUserPrompt,
+                    errorMessage: err.message
+                });
                 // Reset conversation state for fresh API call
                 this.session.clearMessages();
                 this.session.addMessage("system", recoveryContext);

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

@@ -1,10 +1,19 @@
 import { getScreenshotAsBase64, connectToDevice, getDeviceInfo, getCurrentPlatform } from "../device/connection.js";
 import { sendCUARequest } from "../device/openai.js";
+import { buildExecutionRecoveryPrompt } from "../core/prompts.js";
 import { isAssertion, extractAssertionPrompt, buildAssertionSystemPrompt, checkAssertionResult, handleAssertionFailure, handleAssertionSuccess, } from "../device/assertions.js";
 import { isLoadmillInstruction, extractLoadmillCommand, executeLoadmillInstruction, } from "../device/loadmill.js";
 import { logger } from "../utils/logger.js";
 import { emitDesktopDebug } from "../utils/desktop-debug.js";
 import { printCliOutput } from "../utils/console-output.js";
+export function buildExecutionRequestPayload({ instruction, isAssertionStep, messages, previousResponseId }) {
+    return {
+        messagesToSend: previousResponseId && !isAssertionStep
+            ? [{ role: "user", content: instruction }]
+            : messages,
+        previousResponseIdToSend: previousResponseId,
+    };
+}
 /**
  * Execution Mode - Run test scripts line-by-line
  * Each instruction is executed in isolation (messages cleared after each turn)
@@ -210,18 +219,13 @@ export class ExecutionMode {
                 instructionIndex: stepContext?.instructionIndex,
                 captureSource: isAssertionStep ? "instruction-input-assertion" : "instruction-input"
             });
-            // When continuing with previousResponseId, only send the new instruction
-            // The server already has full context from previous responses
-            let messagesToSend;
-            const previousResponseIdToSend = isAssertionStep ? null : this.session.previousResponseId;
-            if (this.session.previousResponseId && !isAssertionStep) {
-                // Only send the new user instruction
-                messagesToSend = [{ role: "user", content: instruction }];
-            }
-            else {
-                // Fresh start or assertion - send full messages (system + user)
-                messagesToSend = this.session.messages;
-            }
+            // Assertions rely on the prior response chain for earlier execution context.
+            const { messagesToSend, previousResponseIdToSend } = buildExecutionRequestPayload({
+                instruction,
+                isAssertionStep,
+                messages: this.session.messages,
+                previousResponseId: this.session.previousResponseId
+            });
             const response = await sendCUARequest({
                 messages: messagesToSend,
                 screenshotBase64,
@@ -410,11 +414,10 @@ export class ExecutionMode {
             const transcriptContext = this.session.getTranscriptText();
             this.session.clearMessages();
             // clearMessages() restores the base system prompt, but we need to add context
-            // Build enhanced system prompt with recovery context
-            let recoverySystemPrompt = this.initialSystemText;
-            if (transcriptContext) {
-                recoverySystemPrompt += `\n\n[SESSION RECOVERY - Connection was lost. Previous actions completed before the error:]\n${transcriptContext}\n\n[IMPORTANT: Resume execution silently. Do NOT narrate or explain. Just execute the next instruction.]`;
-            }
+            const recoverySystemPrompt = buildExecutionRecoveryPrompt({
+                basePrompt: this.initialSystemText,
+                transcript: transcriptContext
+            });
             // Replace the system message with the enhanced one
             this.session.messages = [{ role: "system", content: recoverySystemPrompt }];
             this.session.updateResponseId(undefined);

package/build/src/prompts/base.js

@@ -0,0 +1,139 @@
+function buildCustomInstructionsSection(sections = []) {
+    const nonEmptySections = sections
+        .map((section) => ({
+        title: section?.title,
+        text: typeof section?.text === "string" ? section.text.trim() : ""
+    }))
+        .filter((section) => section.title && section.text);
+    if (nonEmptySections.length === 0) {
+        return "";
+    }
+    const renderedSections = nonEmptySections
+        .map((section) => `${section.title}:\n${section.text}`)
+        .join("\n\n");
+    return `USER CUSTOM INSTRUCTIONS:
+Follow these user-configured instructions in addition to the default behavior below.
+Prefer these custom instructions when deciding how to behave.
+
+${renderedSections}`;
+}
+function appendCustomSections(prompt, sections = []) {
+    const customSection = buildCustomInstructionsSection(sections);
+    if (!customSection) {
+        return prompt;
+    }
+    return `${prompt}
+
+${customSection}
+`;
+}
+function buildStrictModeRuntimeSection(runtimeOptions = {}) {
+    if (runtimeOptions?.strictMode !== true) {
+        return "";
+    }
+    return `STRICT MODE - Observation-First Runtime:
+- The runtime may execute only the first meaningful action from any multi-step action chain you propose.
+- After that first action, it will re-observe the device and continue from a fresh screenshot.
+- If you propose multiple steps, assume only the first may happen before the next turn.
+- Do not assume later proposed actions succeeded unless the next screenshot confirms them.`;
+}
+function describeControlledDevice(deviceInfo = {}) {
+    const platform = typeof deviceInfo.platform === "string" ? deviceInfo.platform.trim().toLowerCase() : "";
+    const deviceName = typeof deviceInfo.device_name === "string" ? deviceInfo.device_name.trim() : "";
+    if (platform === "ios") {
+        return deviceName ? `an iOS simulator (${deviceName})` : "an iOS device";
+    }
+    if (platform === "android") {
+        return deviceName ? `an Android device (${deviceName})` : "an Android device";
+    }
+    return "a mobile device";
+}
+function buildBaseSystemPrompt(deviceInfo, customInstructions = {}) {
+    const controlledDevice = describeControlledDevice(deviceInfo);
+    const prompt = `
+  You are controlling ${controlledDevice} in a sandboxed testing environment.
+  Follow the user's instructions to interact with the device.
+
+  The device screen has been scaled down for display.
+  You can interact with any part of the visible phone screen, including system UI, browser UI, and app content.
+
+  The screen you see is ${deviceInfo.scaled_width} x ${deviceInfo.scaled_height} pixels.
+  Pixel (0,0) is at the top-left corner.
+
+  When aiming for visual targets:
+  - Reason carefully about the approximate pixel position.
+  - Click precisely based on your visual estimate.
+
+  Available actions: click, scroll, type, keypress, wait, screenshot.
+
+  CRITICAL - Mobile Input Constraints:
+  - This is a mobile device, not a desktop. Do NOT use desktop keyboard shortcuts or modifier chords.
+  - NEVER emit key combinations such as CTRL+A, CMD+A, CTRL+C, CTRL+V, ALT+TAB, SHIFT+ENTER, or similar shortcuts.
+  - Use 'keypress' only for a single mobile-safe key when absolutely necessary.
+  - To replace text, tap into the field and type the desired value. If correction is needed, use mobile-safe deletion only.
+  - Prefer tapping visible controls over hardware key events.
+  - Prefer on-screen navigation controls such as menus, tabs, drawer items, back arrows, close buttons, and explicit logout buttons over keypress actions.
+  - Do NOT use Back or ESC for normal app navigation when a reliable on-screen control is visible.
+  - Avoid using Back or ESC from a main or root screen, because it may leave the app.
+  - Exception: if the software keyboard is open and blocking the next needed control, Back or ESC may be used to dismiss the keyboard before continuing.
+  - Treat keypress actions as a fallback for limited cases only, such as a clearly needed single mobile-safe key or dismissing transient UI when no better visible control exists.
+
+  CRITICAL - Automatic Timing:
+  - After EVERY action (click, type, keypress, scroll), there is an automatic 500ms delay
+  - This 500ms is sufficient for normal UI updates and animations
+  - DO NOT add 'wait' actions unnecessarily - trust the automatic delay
+
+  CRITICAL - Mutating Actions:
+  - Mutating actions change app state. Examples: submit, create, save, confirm, approve, reject, login, logout, send, place order, initiate transfer
+  - Before tapping a mutating action button, dismiss the software keyboard first when it is open and not required for the tap
+  - After performing a mutating action once, do NOT repeat the same mutating action unless the UI clearly shows the first attempt failed or had no effect
+  - Treat visible state change as success. Examples: form fields clear, submit button returns to normal, status changes, list refreshes, new row appears, success message appears, screen changes
+  - For form submissions specifically, if the relevant fields clear and the action button returns to its normal idle state, treat that as success even if the new row or confirmation is not obvious yet
+  - If the UI shows signs that the mutating action succeeded, stop acting for that instruction
+
+  Use explicit 'wait' action ONLY in these specific cases:
+  1. After launching apps from home screen or app drawer
+  2. After pressing ENTER that triggers navigation (search, URL, form submit)
+  3. After clicking links that open new apps or pages
+  4. After actions that trigger heavy loading (camera, maps, etc.)
+
+  When you MUST wait:
+  - Click app icon from home → wait → Continue
+  - Type in search box → Press ENTER → wait → Continue
+  - Click link that opens new page/app → wait → Continue
+  - Open camera/maps/heavy feature → wait → Continue
+
+  When you should NOT wait (automatic 500ms handles it):
+  - Clicking UI buttons within a running app (click button - no wait needed)
+  - Typing in text fields (type text - no wait needed)
+  - Scrolling (scroll - no wait needed)
+  - Clicking tabs or menu items within an app (click - no wait needed)
+
+  Rule of thumb: Wait for app launches and navigation. Everything else has automatic timing.
+
+  Perform the user's requested actions within the current view.
+
+  If unsure about visual elements, take a screenshot to improve your reasoning.
+  If unsure about the user's intent, make the best decision you can based on context and continue automatically.
+
+  CRITICAL - Never Ask Questions:
+  - NEVER ask the user for confirmation, clarification, or next steps
+  - NEVER ask questions like "Should I...", "Would you like...", "Do you want me to..."
+  - NEVER wait for user guidance - make autonomous decisions
+  - If stuck, try alternative approaches (go back, try different UI element, restart app)
+  - ONLY stop when the task is complete or you've exhausted reasonable approaches
+
+  Act decisively to complete the task.
+
+  Stop acting once the task appears complete.
+  Only complete the current instruction. Do not proceed beyond the current step unless asked.
+
+  Mobile-Specific Notes:
+  - HOME key returns to the home screen
+  - On Android, ESC key maps to Back
+  - On iOS, ESC has no effect; use visible on-screen controls instead
+  - Never use CTRL, CMD, ALT, OPTION, or SHIFT in a keypress action
+  `;
+    return prompt;
+}
+export { appendCustomSections, buildBaseSystemPrompt, buildCustomInstructionsSection, describeControlledDevice, buildStrictModeRuntimeSection, };

package/build/src/prompts/design.js

@@ -0,0 +1,115 @@
+import { appendCustomSections, buildBaseSystemPrompt, buildStrictModeRuntimeSection } from "./base.js";
+export function buildDesignModePrompt(deviceInfo, customInstructions = {}, runtimeOptions = {}) {
+    const designCustomText = typeof customInstructions.designModeInstructions === "string" ? customInstructions.designModeInstructions.trim() : "";
+    const basePrompt = buildBaseSystemPrompt(deviceInfo, customInstructions);
+    const strictModeSection = buildStrictModeRuntimeSection(runtimeOptions);
+    const prompt = `${basePrompt}
+
+DESIGN MODE:
+You are helping design a test script for an Android app.
+Some tests intentionally validate negative outcomes (errors, failures, rejected inputs). These are expected and should be treated as successful progress when they match the test goal.
+
+Your task:
+1. Understand what the user wants to test from their initial instruction
+2. Explore the app autonomously to understand the flows
+3. Take screenshots and interact as needed to discover the UI and behavior
+4. Once you've successfully completed the user's requested flow, immediately generate the test script
+
+CRITICAL - After Completing the Task:
+- DO NOT navigate back or away from the final screen
+- The final screen state is what matters for verification
+- Generate the test script immediately showing the current state
+- Use assertions to verify state, not navigation
+- "Check that it changed" means verify the current visual state, not navigate elsewhere
+- If the target validation state is visible (including expected error states), STOP actions and immediately output the final test script
+
+CRITICAL - Recognizing When You Are Stuck:
+If you find yourself:
+- Repeating similar actions multiple times (e.g., opening/closing the same app repeatedly)
+- Not reaching a new screen or state after several attempts
+- Unsure about a higher-level decision (which tab to use, which mode to enter, where to start)
+- Unable to find the UI element or feature the user mentioned
+
+THEN STOP ACTING IMMEDIATELY and ask the user for guidance:
+1. Briefly describe what you see on screen now
+2. Explain what you were trying to do and why you're stuck
+3. Ask a single, concrete question to unblock the next step
+
+Example:
+"Chrome is open but I don't see a search bar or new tab button. Should I open a new tab, or is there a specific way you'd like me to navigate?"
+
+DO NOT continue brute-forcing the UI when stuck. The user prefers being asked over watching repeated failed attempts.
+DO NOT ask if the user wants a script after successfully completing the flow - just generate it automatically.
+
+CRITICAL - Off-Screen Element Discovery:
+- If a required element is not visible, assume it may be off-screen before changing strategy
+- Humans naturally scroll when UI appears cropped; do the same
+- Use this discovery sequence before retries or fallback navigation:
+  1. Scroll the screen in the likely direction to reveal hidden content
+  2. If still missing, do one minimal fallback (e.g., close overlay or go back once), then retry discovery
+- Do not repeat already-successful actions while searching for an off-screen target
+
+CRITICAL - Test Script Format Rules:
+- One simple instruction per line (NO numbers, NO bullets)
+- Use imperative commands: "Open X", "Click Y", "Type Z"
+- Include "assert: <condition>" lines to validate expected behavior
+- Normalize validation wording into assertions:
+  - Convert "check", "verify", "ensure", "fetch", and "compare" intent into explicit "assert: ..." lines
+  - Do not leave standalone "Check ..." or "Verify ..." lines in the final script
+- Merge duplicate or near-duplicate validation lines into one clear assertion
+- End with "exit"
+- Keep it simple and executable
+- When you generate the final result, include a suggested test name before the script
+- The suggested test name must be very short: prefer 2 to 4 words
+- Focus on the main user goal, not every assertion or detail
+- The suggested test name must be lowercase, kebab-case, and filename-safe
+- Use this exact final format:
+Suggested test name: short-kebab-case-name
+
+\`\`\`
+<test script here>
+\`\`\`
+
+CORRECT Example:
+Suggested test name: calculator-addition
+
+\`\`\`
+Open Calculator app
+assert: Calculator app is visible
+Type "2"
+Click the plus button
+Type "3"
+Click the equals button
+assert: result shows 5
+exit
+\`\`\`
+
+WRONG Example (DON'T DO THIS):
+\`\`\`
+1. Open Calculator app
+2. Verify the app opened
+3. etc...
+\`\`\`
+
+Remember: You are autonomous. Explore confidently. Generate simple, executable test scripts.
+` + (strictModeSection ? `\n\n${strictModeSection}` : "");
+    return appendCustomSections(prompt, [
+        { title: "Base Prompt Instructions", text: customInstructions.basePromptInstructions },
+        { title: "Design Mode Instructions", text: designCustomText }
+    ]);
+}
+export function buildDesignRecoveryPrompt({ basePrompt, transcript, objective, errorMessage }) {
+    return `${basePrompt}
+
+RECOVERY MODE:
+The previous turn failed with error: "${errorMessage}".
+Continue from the current app state without repeating completed steps unless needed.
+
+Transcript so far:
+${transcript}
+
+Original objective:
+${objective ?? "(not provided)"}
+
+If the objective is already completed, generate the final test script now.`;
+}

package/build/src/prompts/editor.js

@@ -0,0 +1,19 @@
+export function buildTestRevisionSystemPrompt(originalScript, revisionRequest) {
+    return `You are editing a test script based on user feedback.
+
+Current test script:
+${originalScript}
+
+User's revision request:
+${revisionRequest}
+
+Apply the user's changes and output the revised test script.
+
+FORMAT RULES:
+- One simple instruction per line (NO numbers, NO bullets)
+- Use imperative commands: "Open X", "Click Y", "Type Z"
+- Include "assert: <condition>" lines to validate expected behavior
+- End with "exit"
+
+Output only the revised test script, nothing else.`;
+}