@loadmill/droid-cua 2.7.0 → 2.8.0

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

package/build/src/commands/help.js

@@ -10,15 +10,19 @@
  */
 export async function handleHelp(args, session, context) {
     const addOutput = context?.addOutput || ((item) => console.log(item.text || item));
-    addOutput({ type: 'system', text: 'droid-cua - AI-powered mobile device testing CLI' });
+    addOutput({ type: 'system', text: 'droid-cua - AI-powered mobile and web testing CLI' });
     addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Usage:' });
     addOutput({ type: 'info', text: '  droid-cua --avd <device-name> [options]' });
+    addOutput({ type: 'info', text: '  droid-cua --target web --url <starting-url> --instructions <file> [options]' });
     addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Options:' });
+    addOutput({ type: 'info', text: '  --target <kind>        Target kind: mobile (default) or web' });
     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: '  --url <value>          Required starting URL for --target web headless runs' });
+    addOutput({ type: 'info', text: '  --session-mode <mode>  Browser session mode for web runs: persistent or fresh' });
     addOutput({ type: 'info', text: '  --config <file>        Headless execution JSON config for prompt parity' });
     addOutput({ type: 'info', text: '  --cua-model <model>    Headless CUA model override: gpt-5.4, gpt-5.4-mini, or computer-use-preview' });
     addOutput({ type: 'info', text: '  --context <file>       Optional app context file used to brief execution runs' });
@@ -52,6 +56,7 @@ export async function handleHelp(args, session, context) {
     addOutput({ type: 'info', text: 'Platform Support:' });
     addOutput({ type: 'info', text: '  Android: Uses ADB to communicate with Android devices (physical or emulator)' });
     addOutput({ type: 'info', text: '  iOS:     Uses Appium + XCUITest for iOS Simulator automation' });
+    addOutput({ type: 'info', text: '  Web:     Uses Playwright with installed Google Chrome or Microsoft Edge for browser execution' });
     addOutput({ type: 'info', text: '' });
     addOutput({ type: 'info', text: 'Platform Detection:' });
     addOutput({ type: 'info', text: '  - Use --platform flag to force a specific platform' });
@@ -71,6 +76,7 @@ export async function handleHelp(args, session, context) {
     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: '  droid-cua --target web --url docs.example.com --instructions tests/search.dcua' });
     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)' });

package/build/src/core/capture-sources.js

@@ -0,0 +1,76 @@
+// Single source of truth for screenshot/click-annotation provenance. Producers
+// stamp `captureSource` on every event; consumers (renderer log filter, main
+// result-artifact router, debug recorder) read it through classifyCaptureSource.
+//
+// classifyCaptureSource returns three orthogonal axes — each consumer reads only
+// what it needs:
+//   - mediaKind: how the renderer should display the event ('hidden-debug'
+//     hides it from the timeline, 'screenshot' / 'click-annotation' put it in
+//     the gallery, null leaves it as plain text).
+//   - persistsToResults: whether the main process copies the artifact into the
+//     run's user-visible result directory (vs. debug-only).
+//   - visibility: whether the event represents user-facing action ('user'),
+//     internal preview/debug noise ('debug'), or has no associated media
+//     ('none'). Distinct from mediaKind because INSTRUCTION_INPUT and
+//     DESIGN_INPUT are real user inputs but don't appear in the gallery.
+export const CAPTURE_SOURCES = Object.freeze({
+    PREVIEW_CLICK: "preview-click",
+    ACTION_CLICK_ANNOTATION: "action-click-annotation",
+    CALL_OUTPUT_POST_ACTION: "call-output-post-action",
+    CALL_OUTPUT_EXPLICIT_ACTION: "call-output-explicit-action",
+    INSTRUCTION_INPUT: "instruction-input",
+    INSTRUCTION_INPUT_ASSERTION: "instruction-input-assertion",
+    DESIGN_INPUT: "design-input",
+});
+const HIDDEN_DEBUG_MEDIA_KINDS = new Set([
+    CAPTURE_SOURCES.PREVIEW_CLICK,
+]);
+const CLICK_ANNOTATION_MEDIA_KINDS = new Set([
+    CAPTURE_SOURCES.ACTION_CLICK_ANNOTATION,
+]);
+const SCREENSHOT_MEDIA_KINDS = new Set([
+    CAPTURE_SOURCES.CALL_OUTPUT_POST_ACTION,
+    CAPTURE_SOURCES.CALL_OUTPUT_EXPLICIT_ACTION,
+    CAPTURE_SOURCES.INSTRUCTION_INPUT_ASSERTION,
+]);
+const USER_VISIBLE_RESULT_CAPTURE_SOURCES = new Set([
+    CAPTURE_SOURCES.CALL_OUTPUT_POST_ACTION,
+    CAPTURE_SOURCES.CALL_OUTPUT_EXPLICIT_ACTION,
+    CAPTURE_SOURCES.INSTRUCTION_INPUT_ASSERTION,
+    CAPTURE_SOURCES.ACTION_CLICK_ANNOTATION,
+]);
+export function classifyCaptureSource(source) {
+    if (typeof source !== "string" || !source.trim()) {
+        return {
+            mediaKind: null,
+            persistsToResults: false,
+            visibility: "none",
+        };
+    }
+    if (HIDDEN_DEBUG_MEDIA_KINDS.has(source)) {
+        return {
+            mediaKind: "hidden-debug",
+            persistsToResults: false,
+            visibility: "debug",
+        };
+    }
+    if (CLICK_ANNOTATION_MEDIA_KINDS.has(source)) {
+        return {
+            mediaKind: "click-annotation",
+            persistsToResults: true,
+            visibility: "user",
+        };
+    }
+    if (SCREENSHOT_MEDIA_KINDS.has(source)) {
+        return {
+            mediaKind: "screenshot",
+            persistsToResults: true,
+            visibility: "user",
+        };
+    }
+    return {
+        mediaKind: null,
+        persistsToResults: USER_VISIBLE_RESULT_CAPTURE_SOURCES.has(source),
+        visibility: source === CAPTURE_SOURCES.INSTRUCTION_INPUT || source === CAPTURE_SOURCES.DESIGN_INPUT ? "user" : "none",
+    };
+}

package/build/src/core/execution-engine.js

@@ -8,6 +8,7 @@ import { emitDesktopDebug } from "../utils/desktop-debug.js";
 import { getConfiguredStepDelayMs } from "../utils/step-delay.js";
 import { printCliOutput } from "../utils/console-output.js";
 import { annotateScreenshotArtifact, createAnnotatedScreenshotFromBase64 } from "../utils/run-screenshot-recorder.js";
+import { CAPTURE_SOURCES } from "./capture-sources.js";
 const VALID_CUA_MODELS = new Set(["gpt-5.4", "gpt-5.4-mini", "computer-use-preview"]);
 function extractActionableOutputItems(items) {
     const entries = [];
@@ -319,23 +320,51 @@ export class ExecutionEngine {
                 }));
             }
             const previewEventId = randomUUID();
-            await this.recordPreviewScreenshot(previewResult.screenshotBase64, {
+            const previewScreenshotResult = await this.recordPreviewScreenshot(previewResult.screenshotBase64, {
                 runId: context?.runId,
                 sessionId: context?.sessionId,
                 stepId: stepContext?.stepId,
                 instructionIndex: stepContext?.instructionIndex,
                 callId,
                 eventId: previewEventId,
-                captureSource: "preview-click",
+                captureSource: CAPTURE_SOURCES.PREVIEW_CLICK,
             });
+            const previewText = buildPreviewOutputText({
+                requestedX: previewResult.marker.requestedX,
+                requestedY: previewResult.marker.requestedY,
+                renderedX: previewResult.marker.x,
+                renderedY: previewResult.marker.y,
+                wasClamped: previewResult.marker.wasClamped,
+            });
+            const addOutput = context?.addOutput || null;
+            if (addOutput) {
+                const previewScreenshotPath = screenshotPathFromRecorderResult(previewScreenshotResult);
+                const previewScreenshotDataUrl = context?.includeScreenshotDataUrl
+                    ? `data:image/png;base64,${previewResult.screenshotBase64}`
+                    : null;
+                addOutput({
+                    type: "action",
+                    text: "Click",
+                    eventType: "tool_call",
+                    runId: context?.runId,
+                    stepId: stepContext?.stepId,
+                    instructionIndex: stepContext?.instructionIndex,
+                    payload: {
+                        platform: this.session.deviceInfo?.platform,
+                        toolName: "preview_click",
+                        captureSource: CAPTURE_SOURCES.PREVIEW_CLICK,
+                        requestedX: previewResult.marker.requestedX,
+                        requestedY: previewResult.marker.requestedY,
+                        renderedX: previewResult.marker.x,
+                        renderedY: previewResult.marker.y,
+                        wasClamped: previewResult.marker.wasClamped,
+                        ...(previewScreenshotPath ? { screenshotPath: previewScreenshotPath } : {}),
+                        ...(previewScreenshotDataUrl ? { screenshotDataUrl: previewScreenshotDataUrl } : {})
+                    }
+                });
+            }
             return buildFunctionCallOutputItem(callId, buildPreviewOutputContent({
-                text: buildPreviewOutputText({
-                    requestedX: previewResult.marker.requestedX,
-                    requestedY: previewResult.marker.requestedY,
-                    renderedX: previewResult.marker.x,
-                    renderedY: previewResult.marker.y,
-                    wasClamped: previewResult.marker.wasClamped,
-                }),
+                text: previewText,
                 annotatedScreenshotBase64: previewResult.screenshotBase64,
             }));
         }
@@ -465,7 +494,7 @@ export class ExecutionEngine {
                         stepId: stepContext?.stepId,
                         instructionIndex: stepContext?.instructionIndex,
                         eventId: actionEventId,
-                        captureSource: "action-click-annotation"
+                        captureSource: CAPTURE_SOURCES.ACTION_CLICK_ANNOTATION
                     });
                     const annotatedScreenshotPath = screenshotPathFromRecorderResult(annotatedScreenshotResult);
                     const annotatedScreenshotDataUrl = screenshotDataUrlFromRecorderResult(annotatedScreenshotResult);
@@ -475,6 +504,7 @@ export class ExecutionEngine {
                         stepId: stepContext?.stepId,
                         instructionIndex: stepContext?.instructionIndex,
                         eventId: actionEventId,
+                        captureSource: CAPTURE_SOURCES.ACTION_CLICK_ANNOTATION,
                         ...(annotatedScreenshotPath ? { screenshotPath: annotatedScreenshotPath } : {}),
                         ...(context?.includeScreenshotDataUrl && annotatedScreenshotDataUrl ? { screenshotDataUrl: annotatedScreenshotDataUrl } : {})
                     });
@@ -505,7 +535,7 @@ export class ExecutionEngine {
                 base64Length: screenshotBase64.length
             });
             const screenshotEventId = randomUUID();
-            const captureSource = sawExplicitScreenshotAction ? "call-output-explicit-action" : "call-output-post-action";
+            const captureSource = sawExplicitScreenshotAction ? CAPTURE_SOURCES.CALL_OUTPUT_EXPLICIT_ACTION : CAPTURE_SOURCES.CALL_OUTPUT_POST_ACTION;
             const screenshotResult = await this.recordScreenshot(screenshotBase64, {
                 runId: context?.runId,
                 sessionId: context?.sessionId,

package/build/src/core/prompts.js

@@ -1,3 +1,3 @@
 export { buildBaseSystemPrompt } from "../prompts/base.js";
 export { buildDesignModePrompt, buildDesignRecoveryPrompt } from "../prompts/design.js";
-export { buildAppContextSection, buildAssertionSystemPrompt, buildExecutionModePrompt, buildExecutionRecoveryPrompt, } from "../prompts/execution.js";
+export { buildAppContextSection, buildAssertionSystemPrompt, buildExecutionModePrompt, buildExecutionNavigationRecoveryPrompt, buildExecutionRecoveryPrompt, } from "../prompts/execution.js";

package/build/src/core/session.js

@@ -1,11 +1,18 @@
 /**
  * Session manages the state for a single CLI session
- * Includes device info, message history, transcript, and response chaining
+ * Includes target info, message history, transcript, and response chaining
  */
 export class Session {
-    constructor(deviceId, deviceInfo) {
-        this.deviceId = deviceId;
-        this.deviceInfo = deviceInfo;
+    constructor(targetSessionId, targetInfo) {
+        this.deviceId = targetSessionId;
+        this.deviceInfo = targetInfo;
+        this.deviceName = targetInfo?.device_name || null;
+        this.browserSessionId = targetInfo?.platform === "browser" ? targetSessionId : null;
+        this.browserInfo = targetInfo?.platform === "browser" ? targetInfo : null;
+        this.browserName = targetInfo?.browserName || null;
+        this.currentUrl = targetInfo?.currentUrl || null;
+        this.sessionMode = targetInfo?.sessionMode || null;
+        this.targetKind = targetInfo?.platform === "browser" ? "browser" : "mobile";
         this.messages = [];
         this.previousResponseId = null;
         this.transcript = [];
@@ -54,4 +61,11 @@ export class Session {
     updateResponseId(responseId) {
         this.previousResponseId = responseId;
     }
+    /**
+     * Replace the active system prompt for the next turn and start a fresh response chain.
+     */
+    installRecoverySystemPrompt(prompt) {
+        this.messages = [{ role: "system", content: prompt }];
+        this.updateResponseId(null);
+    }
 }

package/build/src/device/action-event-meta.js

@@ -0,0 +1,18 @@
+export function buildActionEventMeta({ context, action, platform, payload = {}, extraPayload = {} }) {
+    return {
+        eventType: "tool_call",
+        actionType: action?.type,
+        runId: context?.runId,
+        stepId: context?.stepId,
+        instructionIndex: context?.instructionIndex,
+        payload: {
+            eventId: context?.eventId,
+            screenshotPath: context?.screenshotPath,
+            screenshotDataUrl: context?.screenshotDataUrl,
+            captureSource: context?.captureSource,
+            platform,
+            ...extraPayload,
+            ...payload,
+        },
+    };
+}

package/build/src/device/android/actions.js

@@ -1,6 +1,7 @@
 import { logger } from "../../utils/logger.js";
 import { emitDesktopDebug, truncateForDebug } from "../../utils/desktop-debug.js";
 import { getConfiguredStepDelayMs } from "../../utils/step-delay.js";
+import { buildActionEventMeta } from "../action-event-meta.js";
 import { resolveScrollGesture } from "../scroll-gesture.js";
 import { execAdb } from "./tools.js";
 function adbShell(deviceId, command) {
@@ -33,19 +34,11 @@ function normalizeMobileKeypress(keys = []) {
 }
 export async function handleModelAction(deviceId, action, scale = 1.0, context = null) {
     const addOutput = context?.addOutput || ((item) => console.log(item.text || item));
-    const meta = (payload = {}) => ({
-        eventType: 'tool_call',
-        actionType: action?.type,
-        runId: context?.runId,
-        stepId: context?.stepId,
-        instructionIndex: context?.instructionIndex,
-        payload: {
-            eventId: context?.eventId,
-            screenshotPath: context?.screenshotPath,
-            screenshotDataUrl: context?.screenshotDataUrl,
-            platform: 'android',
-            ...payload
-        }
+    const meta = (payload = {}) => buildActionEventMeta({
+        context,
+        action,
+        platform: 'android',
+        payload
     });
     try {
         const { x, y, x1, y1, x2, y2, text, keys, path } = action;

package/build/src/device/cloud/actions.js

@@ -1,6 +1,7 @@
 import { logger } from "../../utils/logger.js";
 import { emitDesktopDebug, truncateForDebug } from "../../utils/desktop-debug.js";
 import { getConfiguredStepDelayMs } from "../../utils/step-delay.js";
+import { buildActionEventMeta } from "../action-event-meta.js";
 import { getActiveSession, getDevicePixelRatio } from "./connection.js";
 import { resolveScrollGesture } from "../scroll-gesture.js";
 function normalizeMobileKeypress(platform, keys = []) {
@@ -47,20 +48,14 @@ export async function handleModelAction(deviceId, action, scale = 1.0, context =
     const addOutput = context?.addOutput || ((item) => console.log(item.text || item));
     const session = getActiveSession();
     const platform = session?.platform;
-    const meta = (payload = {}) => ({
-        eventType: "tool_call",
-        actionType: action?.type,
-        runId: context?.runId,
-        stepId: context?.stepId,
-        instructionIndex: context?.instructionIndex,
-        payload: {
-            eventId: context?.eventId,
-            screenshotPath: context?.screenshotPath,
-            screenshotDataUrl: context?.screenshotDataUrl,
-            platform,
-            source: session?.providerId,
-            ...payload
-        }
+    const meta = (payload = {}) => buildActionEventMeta({
+        context,
+        action,
+        platform,
+        extraPayload: {
+            source: session?.providerId
+        },
+        payload
     });
     if (!session || !platform) {
         throw new Error("No active cloud session");

package/build/src/device/cloud/connection.js

@@ -103,6 +103,14 @@ export function getActiveSession() {
 export function getDevicePixelRatio() {
     return activeSession?.devicePixelRatio || 1;
 }
+// Test-only — do not call from production code. Used by unit tests to install
+// a fake session without going through the real cloud-provider connect flow.
+export function setActiveSessionForTests(session) {
+    activeSession = session;
+}
+export function clearActiveSessionForTests() {
+    activeSession = null;
+}
 export async function disconnect() {
     if (!activeSession) {
         return;