@loadmill/droid-cua 2.43.0 → 2.44.0

package/build/src/device/ios/real-device/wda-provisioning.js

@@ -0,0 +1,229 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { access, copyFile, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { chooseSigning, PROFILE_DIRS, runProvisioningBuild, wdaRunnerBundleId } from "./signing.js";
+const execFileAsync = promisify(execFile);
+export const APPIUM_WDA_DIR = path.join(os.homedir(), ".appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent");
+const DATA_DIR = path.join(os.homedir(), ".droid-cua", "ios-devices");
+const ZIP_NAME = "WebDriverAgentRunner-Runner.zip";
+const APP_NAME = "WebDriverAgentRunner-Runner.app";
+const XCTEST_NAME = "WebDriverAgentRunner.xctest";
+const RETRYABLE_BUILD_ERRORS = ["certificate-missing", "unknown"];
+const defaultRunner = (cmd, args) => execFileAsync(cmd, args, { maxBuffer: 64 * 1024 * 1024 });
+let runner = defaultRunner;
+export function __setWdaRunner(run = null) {
+    runner = run || defaultRunner;
+}
+export class WdaProvisioningError extends Error {
+    constructor({ kind, message, details }) {
+        super(message);
+        this.name = "WdaProvisioningError";
+        this.kind = kind;
+        if (details)
+            this.details = details;
+    }
+}
+async function exists(file) {
+    return access(file).then(() => true, () => false);
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+export function wdaBundleIdBase(teamId) {
+    return `com.droidcua.${teamId.toLowerCase()}.WebDriverAgentRunner`;
+}
+export function wdaCacheDir(version) {
+    return path.join(DATA_DIR, "wda", version);
+}
+export function wdaDownloadUrl(version) {
+    return `https://github.com/appium/WebDriverAgent/releases/download/v${version}/${ZIP_NAME}`;
+}
+export async function getPinnedWdaVersion({ wdaDir = APPIUM_WDA_DIR } = {}) {
+    try {
+        return JSON.parse(await readFile(path.join(wdaDir, "package.json"), "utf8")).version;
+    }
+    catch {
+        throw new WdaProvisioningError({
+            kind: "wda-not-installed",
+            message: "Appium's XCUITest driver isn't installed, so droid can't tell which WebDriverAgent version to use.",
+        });
+    }
+}
+export async function downloadWda({ version, cacheDir = wdaCacheDir(version), fetchImpl = fetch }) {
+    const zipPath = path.join(cacheDir, ZIP_NAME);
+    const recordPath = path.join(cacheDir, "download.json");
+    const record = await readFile(recordPath, "utf8").then(JSON.parse, () => null);
+    if (record?.sha256 && (await exists(zipPath))) {
+        const actual = sha256(await readFile(zipPath));
+        if (actual !== record.sha256) {
+            throw new WdaProvisioningError({
+                kind: "checksum-mismatch",
+                message: `The cached WebDriverAgent ${version} download doesn't match its recorded checksum. Delete ${cacheDir} and retry.`,
+            });
+        }
+        return { zipPath, sha256: actual, downloaded: false };
+    }
+    const url = wdaDownloadUrl(version);
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new WdaProvisioningError({
+            kind: "download-failed",
+            message: `Downloading WebDriverAgent ${version} failed (HTTP ${response.status} from ${url}).`,
+        });
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    const actual = sha256(bytes);
+    if (record?.sha256 && actual !== record.sha256) {
+        throw new WdaProvisioningError({
+            kind: "checksum-mismatch",
+            message: `The WebDriverAgent ${version} download doesn't match the checksum recorded on first download. Delete ${cacheDir} and retry.`,
+        });
+    }
+    await mkdir(cacheDir, { recursive: true });
+    const tempPath = `${zipPath}.${process.pid}.tmp`;
+    await writeFile(tempPath, bytes);
+    await rename(tempPath, zipPath);
+    if (!record) {
+        await writeFile(recordPath, `${JSON.stringify({ version, url, sha256: actual, bytes: bytes.length, downloadedAt: new Date().toISOString() }, null, 2)}\n`);
+    }
+    return { zipPath, sha256: actual, downloaded: true };
+}
+async function innerCode(dir) {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const found = [];
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            found.push(...(await innerCode(full)));
+            if (entry.name.endsWith(".framework"))
+                found.push(full);
+        }
+        else if (entry.name.endsWith(".dylib")) {
+            found.push(full);
+        }
+    }
+    return found;
+}
+export function runnerEntitlementsPlist(teamId, bundleIdBase) {
+    const appId = `${teamId}.${wdaRunnerBundleId(bundleIdBase)}`;
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>application-identifier</key>
+  <string>${appId}</string>
+  <key>com.apple.developer.team-identifier</key>
+  <string>${teamId}</string>
+  <key>get-task-allow</key>
+  <true/>
+  <key>keychain-access-groups</key>
+  <array>
+    <string>${appId}</string>
+  </array>
+</dict>
+</plist>
+`;
+}
+function codesign(identity, target, extraArgs = []) {
+    return runner("codesign", ["--force", "--sign", identity.sha1, "--timestamp=none", "--generate-entitlement-der", ...extraArgs, target]);
+}
+export async function prepareSignedWda({ version, bundleIdBase, identity, profile, workDir, zipPath = path.join(wdaCacheDir(version), ZIP_NAME) }) {
+    const appPath = path.join(workDir, APP_NAME);
+    const xctestPath = path.join(appPath, "PlugIns", XCTEST_NAME);
+    await rm(appPath, { recursive: true, force: true });
+    await mkdir(workDir, { recursive: true });
+    await runner("unzip", ["-q", "-o", zipPath, "-d", workDir]);
+    if (!(await exists(appPath))) {
+        throw new WdaProvisioningError({ kind: "bad-download", message: `${APP_NAME} was not found in the WebDriverAgent ${version} download.` });
+    }
+    await runner("plutil", ["-replace", "CFBundleIdentifier", "-string", wdaRunnerBundleId(bundleIdBase), path.join(appPath, "Info.plist")]);
+    await runner("plutil", ["-replace", "CFBundleIdentifier", "-string", bundleIdBase, path.join(xctestPath, "Info.plist")]);
+    await rm(path.join(appPath, "PlugIns", `${XCTEST_NAME}.dSYM`), { recursive: true, force: true });
+    const inner = [...(await innerCode(path.join(xctestPath, "Frameworks"))), ...(await innerCode(path.join(appPath, "Frameworks")))];
+    for (const target of inner)
+        await codesign(identity, target);
+    await codesign(identity, xctestPath);
+    const entitlementsPath = path.join(workDir, "entitlements.plist");
+    await writeFile(entitlementsPath, runnerEntitlementsPlist(profile.teamId, bundleIdBase));
+    await copyFile(profile.path, path.join(appPath, "embedded.mobileprovision"));
+    await codesign(identity, appPath, ["--entitlements", entitlementsPath]);
+    try {
+        await runner("codesign", ["--verify", "--deep", "--strict", appPath]);
+    }
+    catch (error) {
+        throw new WdaProvisioningError({
+            kind: "signature-invalid",
+            message: `The signed WebDriverAgent failed verification: ${(error.stderr || error.message || "").trim()}`,
+        });
+    }
+    return appPath;
+}
+export async function ensureSigning({ udid, teamId, bundleIdBase = wdaBundleIdBase(teamId), wdaDir = APPIUM_WDA_DIR, derivedDataPath = path.join(DATA_DIR, "provisioning-build", teamId), profileDirs = PROFILE_DIRS, onProgress = () => { }, onOutput, }) {
+    onProgress({ step: "signing", message: "Looking for your signing certificate and provisioning profile" });
+    const found = await chooseSigning({ teamId, bundleIdBase, udid, profileDirs });
+    if (found.profile)
+        return { ...found, provisioningBuild: null };
+    onProgress({ step: "provisioning-build", message: `${found.reason} Running the one-time signing build (about a minute).` });
+    let attempts = 0;
+    let durationMs = 0;
+    let build;
+    do {
+        attempts++;
+        build = await runProvisioningBuild({ teamId, bundleIdBase, udid, wdaProjectDir: wdaDir, derivedDataPath, onOutput });
+        durationMs += build.durationMs;
+    } while (!build.ok && attempts < 2 && RETRYABLE_BUILD_ERRORS.includes(build.error.kind));
+    if (!build.ok)
+        throw new WdaProvisioningError(build.error);
+    onProgress({ step: "signing", message: "Looking for the provisioning profile Xcode created" });
+    const after = await chooseSigning({ teamId, bundleIdBase, udid, profileDirs });
+    if (!after.profile) {
+        throw new WdaProvisioningError({
+            kind: "profile-missing",
+            message: `The signing build passed but no usable profile was found. ${after.reason}`,
+        });
+    }
+    return { ...after, provisioningBuild: { attempts, durationMs } };
+}
+export async function provisionWda({ udid, teamId, bundleIdBase = wdaBundleIdBase(teamId), version, wdaDir = APPIUM_WDA_DIR, cacheDir, workDir, derivedDataPath = path.join(DATA_DIR, "provisioning-build", teamId), profileDirs = PROFILE_DIRS, fetchImpl = fetch, onProgress = () => { }, onOutput, installApp, listApps, }) {
+    installApp ??= (await import("./devicectl.js")).installApp;
+    listApps ??= (await import("./devicectl.js")).listApps;
+    const runnerBundleId = wdaRunnerBundleId(bundleIdBase);
+    const signing = await ensureSigning({ udid, teamId, bundleIdBase, wdaDir, derivedDataPath, profileDirs, onProgress, onOutput });
+    version ??= await getPinnedWdaVersion({ wdaDir });
+    cacheDir ??= wdaCacheDir(version);
+    onProgress({ step: "download", message: `Getting WebDriverAgent ${version}` });
+    const download = await downloadWda({ version, cacheDir, fetchImpl });
+    onProgress({ step: "sign", message: `Signing WebDriverAgent as ${signing.identity.name}` });
+    const appPath = await prepareSignedWda({
+        version,
+        bundleIdBase,
+        identity: signing.identity,
+        profile: signing.profile,
+        workDir: workDir ?? path.join(cacheDir, "signed", teamId),
+        zipPath: download.zipPath,
+    });
+    onProgress({ step: "install", message: "Installing WebDriverAgent on the iPhone" });
+    await installApp(udid, appPath);
+    onProgress({ step: "confirm", message: "Checking WebDriverAgent is on the iPhone" });
+    const apps = await listApps(udid, { includeAll: true });
+    if (!apps.some((app) => app.bundleIdentifier === runnerBundleId)) {
+        throw new WdaProvisioningError({
+            kind: "install-not-confirmed",
+            message: `WebDriverAgent (${runnerBundleId}) was installed but doesn't show up in the iPhone's app list.`,
+        });
+    }
+    return {
+        runnerBundleId,
+        bundleIdBase,
+        version,
+        sha256: download.sha256,
+        appPath,
+        identity: signing.identity,
+        profile: signing.profile,
+        signingReason: signing.reason,
+        provisioningBuild: signing.provisioningBuild,
+    };
+}

package/build/src/network/certificate-authority.js

@@ -10,6 +10,8 @@ export function getCertificatePaths(directory = path.join(os.homedir(), ".droid-
         privateKey: path.join(directory, "ca-key.pem"),
         displayName: path.join(directory, "ca-name.json"),
         preparedDevices: path.join(directory, "prepared-devices.json"),
+        iphoneCertificates: path.join(directory, "iphone"),
+        androidCertificates: path.join(directory, "android"),
     };
 }
 function inspectCertificate(certificate, privateKey) {
@@ -163,7 +165,25 @@ export async function generateCertificateAuthority(directory) {
 }
 export async function removeCertificateAuthority(directory) {
     const paths = getCertificatePaths(directory);
-    await Promise.all([paths.certificate, paths.privateKey, paths.displayName, paths.preparedDevices].map((file) => rm(file, { force: true })));
+    await Promise.all([paths.certificate, paths.privateKey, paths.displayName, paths.preparedDevices, paths.iphoneCertificates, paths.androidCertificates].map((file) => rm(file, { recursive: true, force: true })));
+}
+export function certificateCommonName(certificatePem) {
+    const value = forge.pki.certificateFromPem(certificatePem).subject.getField("CN")?.value;
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+async function writeDeviceCertificate(folder, name, extension, contents) {
+    const fileName = `${name.replace(/[^A-Za-z0-9 ._-]+/g, "_").replace(/^[\s.]+|[\s.]+$/g, "") || "Droid CUA Root"}${extension}`;
+    const target = path.join(folder, fileName);
+    await rm(folder, { recursive: true, force: true });
+    await mkdir(folder, { recursive: true, mode: 0o700 });
+    await writeFile(target, contents, { mode: 0o600 });
+    return target;
+}
+export async function writeIphoneCertificate(certificatePem, name, directory) {
+    return writeDeviceCertificate(getCertificatePaths(directory).iphoneCertificates, name, ".cer", new X509Certificate(certificatePem).raw);
+}
+export async function writeAndroidCertificate(certificatePem, name, directory) {
+    return writeDeviceCertificate(getCertificatePaths(directory).androidCertificates, name, ".crt", new X509Certificate(certificatePem).toString());
 }
 export async function ensureCertificateAuthority(directory) {
     const paths = getCertificatePaths(directory);

package/build/src/network/certificate-install.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 import { getCertificatePaths, loadCertificateAuthority } from "./certificate-authority.js";
+import { macLanAddresses, NETWORK_PROXY_PORT } from "./local-proxy.js";
 const execFileAsync = promisify(execFile);
 const MISSING = "__DROID_CERT_MISSING__";
 const APEX_CERTS = "/apex/com.android.conscrypt/cacerts";
@@ -182,6 +183,43 @@ async function installMountedAndroid(adbPath, serial, ca, directory) {
         throw new Error("The Droid CA is not visible from Android's application mount namespace.");
     return { changed: true };
 }
+export function iphoneCertificateInstructions({ certificateName, addresses = macLanAddresses(), port = NETWORK_PROXY_PORT }) {
+    const server = addresses.length > 0 ? addresses.join(" or ") : "this Mac's Wi-Fi IP address";
+    return [
+        "1. Click Send to iPhone and choose AirDrop → your iPhone. Then on the iPhone: Settings → Profile Downloaded → Install.",
+        `2. Settings → General → About → Certificate Trust Settings → turn on full trust for ${certificateName}.`,
+        `3. On the same Wi-Fi as this Mac: Settings → Wi-Fi → (i) → Configure Proxy → Manual: server ${server}, port ${port}.`,
+        "4. Turn the iPhone proxy off when you're done, or the iPhone loses internet access while Droid isn't running.",
+    ].join("\n\n");
+}
+export function iphoneCertificateSummary({ certificateName, addresses = macLanAddresses(), port = NETWORK_PROXY_PORT }) {
+    const proxy = addresses.length > 0 ? addresses.map((address) => `${address}:${port}`).join(" or ") : `this Mac's Wi-Fi IP address, port ${port}`;
+    return `iPhone network capture setup: trust ${certificateName}, proxy ${proxy}.`;
+}
+export async function pushAndroidPhoneCertificate(adbPath, serial, localPath) {
+    const remotePath = `/sdcard/Download/${path.basename(localPath)}`;
+    await adb(adbPath, serial, ["push", localPath, remotePath]);
+    return remotePath;
+}
+export function androidCertificateInstructions({ localPath, pushed, addresses = macLanAddresses(), port = NETWORK_PROXY_PORT }) {
+    const fileName = path.basename(localPath);
+    const server = addresses.length > 0 ? addresses.join(" or ") : "this Mac's Wi-Fi IP address";
+    const steps = [
+        ...(pushed ? [] : [`Droid could not copy the certificate to the phone. Copy ${localPath} to the phone's Downloads folder.`]),
+        `On the Android phone: Settings → Security → Encryption & credentials → Install a certificate → CA certificate, then pick ${fileName} from Downloads. Names vary by vendor; search Settings for "CA certificate".`,
+        `On the same Wi-Fi as this Mac: Settings → Wi-Fi → Edit network → Proxy → Manual: hostname ${server}, port ${port}.`,
+        "Restart the tested app.",
+        "Turn the phone proxy off when you're done, or the phone loses internet access while Droid isn't running.",
+    ];
+    return [
+        ...steps.map((step, index) => `${index + 1}. ${step}`),
+        "Since Android 7, apps trust user-installed CAs only when their network security config allows it, typically debug or QA builds. Chrome trusts them.",
+    ].join("\n\n");
+}
+export function androidCertificateSummary({ certificateName, addresses = macLanAddresses(), port = NETWORK_PROXY_PORT }) {
+    const proxy = addresses.length > 0 ? addresses.map((address) => `${address}:${port}`).join(" or ") : `this Mac's Wi-Fi IP address, port ${port}`;
+    return `Android phone network capture setup: install ${certificateName} as a CA certificate, proxy ${proxy}.`;
+}
 export async function inspectNetworkDevice({ platform, deviceId, adbPath = process.env.DROID_CUA_ANDROID_ADB_PATH || "adb" }) {
     if (platform === "ios") {
         if (process.platform !== "darwin")

package/build/src/network/local-proxy.js

@@ -2,11 +2,30 @@ import { generateKeyPairSync, randomBytes, randomUUID } from "node:crypto";
 import http from "node:http";
 import https from "node:https";
 import net from "node:net";
+import os from "node:os";
 import forge from "node-forge";
 import { loadCertificateAuthority } from "./certificate-authority.js";
 import { BODY_CAPTURE_LIMIT } from "./network-capture.js";
 export const NETWORK_PROXY_HOST = "127.0.0.1";
 export const NETWORK_PROXY_PORT = 8765;
+export const LAN_PROXY_HOST = "0.0.0.0";
+export function macLanAddresses(interfaces = os.networkInterfaces()) {
+    return Object.values(interfaces).flat()
+        .filter((entry) => entry && (entry.family === "IPv4" || entry.family === 4) && !entry.internal && !entry.address.startsWith("169.254."))
+        .map((entry) => entry.address);
+}
+export function iphoneProxyInstruction(addresses = macLanAddresses(), port = NETWORK_PROXY_PORT) {
+    if (addresses.length === 0) {
+        throw new Error("This Mac has no network address an iPhone can reach. Connect the Mac and the iPhone to the same Wi-Fi network.");
+    }
+    return `On the iPhone, set Wi-Fi → Configure Proxy → Manual: server ${addresses.join(" or ")}, port ${port}.`;
+}
+export function androidProxyInstruction(addresses = macLanAddresses(), port = NETWORK_PROXY_PORT) {
+    if (addresses.length === 0) {
+        throw new Error("This Mac has no network address an Android phone can reach. Connect the Mac and the Android phone to the same Wi-Fi network.");
+    }
+    return `On the Android phone, set Wi-Fi → Edit network → Proxy → Manual: hostname ${addresses.join(" or ")}, port ${port}.`;
+}
 function destination(authority) {
     const url = new URL(`http://${authority}`);
     const port = Number(url.port || 443);
@@ -134,7 +153,8 @@ export function createNetworkProxy({ host = NETWORK_PROXY_HOST, port = NETWORK_P
         response.end();
     }
     function isSelf(target) {
-        return target.port === server?.address()?.port && [host, "localhost", "127.0.0.1"].includes(target.host);
+        return target.port === server?.address()?.port &&
+            [host, "localhost", "127.0.0.1", LAN_PROXY_HOST, ...macLanAddresses()].includes(target.host);
     }
     function handleRequest(request, response) {
         const emit = activeEvents;

package/build/src/network/run-network-capture.js

@@ -1,6 +1,6 @@
 import { createLiveNetworkQuery } from "./query-network.js";
 import { createNetworkCapture } from "./network-capture.js";
-import { createNetworkProxy } from "./local-proxy.js";
+import { createNetworkProxy, NETWORK_PROXY_HOST } from "./local-proxy.js";
 import { captureBrowserNetwork } from "./browser-capture.js";
 /** @typedef {{ path: string, source: string, health: import("./network-capture.js").CaptureHealth, failure: Error | null }} CaptureResult */
 export function createRunNetworkCapture({ createProxy = createNetworkProxy, createCapture = createNetworkCapture, onError = (_error) => { } } = {}) {
@@ -8,11 +8,22 @@ export function createRunNetworkCapture({ createProxy = createNetworkProxy, crea
     let query = null;
     let stopRecording = null;
     let source = "proxy";
-    const proxy = createProxy({ onError });
+    let proxyHost = NETWORK_PROXY_HOST;
+    let proxy = createProxy({ host: proxyHost, onError });
     return {
         get query() { return query; },
         get address() { return proxy.address; },
-        startProxy: () => proxy.start(),
+        get host() { return proxyHost; },
+        async startProxy({ host = NETWORK_PROXY_HOST } = {}) {
+            if (host !== proxyHost) {
+                if (capture)
+                    throw new Error("Network capture is active.");
+                await proxy.stop();
+                proxyHost = host;
+                proxy = createProxy({ host, onError });
+            }
+            return proxy.start();
+        },
         async stopProxy() {
             if (capture)
                 throw new Error("Network capture is active.");
@@ -94,9 +105,9 @@ export function describeNetworkCapture({ health, failure, source = "proxy" }) {
             : `Captured ${health.requests} browser requests; ${health.errors} capture or request errors.`;
     }
     if (health.requests === 0 && health.httpsConnects === 0)
-        return "No traffic observed; check proxy routing.";
+        return "No traffic observed; check the device proxy settings.";
     if (health.httpsConnects > 0 && health.decryptedHttpsRequests === 0) {
-        return `HTTPS reached the proxy but no requests were decrypted (${health.tlsErrors} TLS errors). Check certificate trust.`;
+        return `HTTPS reached the proxy but no requests were decrypted (${health.tlsErrors} TLS errors). Check certificate trust on the device.`;
     }
     return `Captured ${health.requests} requests (${health.decryptedHttpsRequests} decrypted HTTPS); ${health.tlsErrors} TLS errors.`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loadmill/droid-cua",
-  "version": "2.43.0",
+  "version": "2.44.0",
   "description": "AI-powered Android testing agent using OpenAI's computer-use model and ADB",
   "main": "build/index.js",
   "type": "module",

package/skill/droid-cua/SKILL.md

@@ -2,7 +2,7 @@
 name: droid-cua
 description: Operate and improve Droid CUA `.dcua` test projects. Use when the user explicitly names Droid CUA or @loadmill/droid-cua, or asks to author, configure, run, diagnose, heal, stabilize, or speed up `.dcua` tests with the Droid CUA CLI or desktop app. Do not use for general web browsing, website development, browser automation, generic mobile work, or non-Droid test tasks.
 metadata:
-  version: "1.0.17"
+  version: "1.1.7"
 ---
 
 # Droid CUA
@@ -13,7 +13,7 @@ Use the existing `droid-cua` CLI and repository files. Do not invent commands, f
 
 1. Inspect the active test project before creating files. Find existing `.dcua` tests, `context.md`, `test-data.md`, `.secrets`, `.env`, and `ci/droid-cua.json` without reading secret values. Do not search other projects or the user's home directory for credentials.
 2. Determine the requested platform and target from the task or project. Ask the user only when the choice is unclear.
-3. Check authentication and environment readiness before the first run. Read [project-and-auth.md](references/project-and-auth.md) for project boundaries and token handling. Read [onboarding-and-troubleshooting.md](references/onboarding-and-troubleshooting.md) when setup, dependency, device, simulator, browser, or connection work is needed.
+3. Check authentication and environment readiness before the first run. Read [project-and-auth.md](references/project-and-auth.md) for project boundaries and token handling. Read [onboarding-and-troubleshooting.md](references/onboarding-and-troubleshooting.md) when setup, dependency, device, simulator, USB iPhone, browser, or connection work is needed.
 4. Identify the intended coverage, starting state, scenario inputs, and cleanup; author or update the smallest useful test that preserves them. Read [authoring-tests.md](references/authoring-tests.md) before changing `.dcua`, context, test data, secrets, or config.
 5. Before execution, present the proposed tests and target to the user, resolve any questions, and get their confirmation. Read [running-and-healing.md](references/running-and-healing.md) for the required pre-run check.
 6. Run the confirmed, narrowest relevant test and monitor it to completion. Keep the user oriented during the run by surfacing meaningful live screenshots, not just terminal output.

package/skill/droid-cua/references/authoring-tests.md

@@ -108,7 +108,7 @@ Droid searches for the best matching Loadmill flow, starts it, and waits for it
 
 ## Validate captured network traffic
 
-For local Chrome, Edge, iOS Simulator or Android Emulator runs with Network Capture enabled, describe HTTP expectations in natural language. Keep the action and its network verification distinct, and name enough of the endpoint and method to identify the intended traffic:
+For local Chrome, Edge, iPhone, iOS Simulator, Android phone or Android Emulator runs with Network Capture enabled, describe HTTP expectations in natural language. Keep the action and its network verification distinct, and name enough of the endpoint and method to identify the intended traffic:
 
 ```text
 Open the Home page.

package/skill/droid-cua/references/onboarding-and-troubleshooting.md

@@ -84,6 +84,37 @@ Use `--platform ios --avd "<simulator name>"` for the run.
 
 For network capture, use **Tools → Manage Certificates** to select the active CA, connect the simulator, and use **Tools → Install Network Certificate**. If no CA exists, installation generates a Droid CA. The CLI assumes the simulator already trusts the active CA. Configure the Mac's proxy manually, then enable desktop **Network Capture** or run a local mobile CLI test with `--capture-network`. Follow the approval rule above before changing simulator trust on the user's behalf.
 
+## iPhone over USB
+
+A real iPhone connected to the Mac by USB is a local, attended target: the user must keep it nearby and unlocked. It needs macOS, Xcode that supports the iPhone's iOS, the XCUITest driver, and the user's Apple ID in Xcode on their company's paid Apple Developer team (Developer role with Access to Certificates, Identifiers & Profiles). Free Apple IDs are not supported. Simulators are not needed.
+
+Check readiness without starting a test:
+
+```sh
+droid-cua ios-device check
+```
+
+Each line is one check: `✔` passed, `✖` failed, `·` not checked yet because an earlier check failed, and `!` a non-blocking reminder (Auto-Lock, test-only iPhone). The `Fix:` line under a `✖` is the exact remediation. Work on the first `✖` only, then rerun the check. Exit `0` means ready, and the last line gives the `--avd ios-device:<udid>` token to run with. Add `--udid <udid>` when several iPhones are connected.
+
+Interpret failures:
+
+- **Xcode installed** or **Device components**: the user must install or update the Xcode named in the message and open it once (it asks for a Mac admin password). When the message says Xcode isn't in the Applications folder, the user must install it or move it to `/Applications`. When it says the Command Line Tools are selected or the license isn't accepted, the `Fix:` line gives the exact `sudo xcode-select -s` or `sudo xcodebuild -license accept` command; get approval before running either.
+- **iOS platform installed**: Xcode lacks the iOS platform for its SDK (Xcode 26 ships without it), so it can't build for an iPhone or fetch the user's Apple teams. The user installs it from Xcode > Settings > Components, or runs `xcodebuild -downloadPlatform iOS`. It's about 10 GB, so get approval before running the command and expect it to take a while.
+- **Apple team access**: on a fresh Mac the check fetches the user's teams from Apple with a short Xcode build within the same run. "No Apple account is signed into Xcode" means the user must sign in (Xcode > Settings > Apple Accounts). "Signed into Xcode, but none of your accounts is in a paid Apple Developer team" means the user must ask their Apple team admin for the Developer role with Access to Certificates, Identifiers & Profiles. With several teams, ask the user which team to use and pass `--ios-team <TEAMID>`; never choose a team for them.
+- **iPhone connected**, **iPhone trusts this Mac**, **Developer Mode**, **iPhone unlocked**: steps only the user can do on the phone. Relay the `Fix:` text, wait for them to confirm, then rerun the check. Turning on Developer Mode restarts the iPhone.
+- **Signing ready** and **Helper app (WebDriverAgent)**: droid-cua fixes these itself. Get approval before the first `droid-cua ios-device check --fix`: it runs a one-time Xcode signing build (about a minute) that can create the user's Apple Development certificate and register the iPhone on their company team. A test run also applies these fixes automatically.
+- **Signing ready** failing with "There's no usable Apple Development certificate for your team on this Mac": a rerun won't help. Relay the `Fix:` line: the user creates an Apple Development certificate for the team in Xcode (Xcode > Settings > Apple Accounts > select the account > select the team > Manage Certificates > + > Apple Development) or on the Apple Developer website (developer.apple.com > Certificates, Identifiers & Profiles > Certificates), or asks their Apple Developer team admin for one if they don't have permission, then reruns the fix. Never revoke a certificate yourself or suggest revoking one.
+
+Never restart, reset, or change settings on the user's iPhone yourself. Do not run `xcodebuild`, `codesign`, or `devicectl` to work around a failing check; use `ios-device check`.
+
+### iPhone network capture
+
+Network capture on an iPhone needs manual setup on the phone, done by the user. The Mac and iPhone must share a Wi-Fi network that allows device-to-device traffic (guest and many corporate networks block it). With an iPhone connected, desktop **Tools → Install Network Certificate** shows the steps instead of installing anything: its **Send to iPhone** button opens the macOS share menu with a `.cer` copy of the CA (named after the certificate's common name, such as `Droid CUA Root fbd877ab.cer`, in `~/.droid-cua/network/iphone/`) to AirDrop to the iPhone; the user installs it from Settings → Profile Downloaded, then turns on full trust for that common name in Settings → General → About → Certificate Trust Settings. The user then sets Wi-Fi → Configure Proxy → Manual to the Mac address and port `8765` that Droid prints, and turns the proxy off after testing, since the iPhone loses internet access through it while Droid is not running. Apps that pin certificates still work through the proxy, but their HTTPS is not decrypted. Relay these steps; never change the iPhone's certificate, trust, or proxy settings yourself.
+
+### Android phone network capture
+
+A physical Android phone connected over ADB also needs manual setup by the user, on a Wi-Fi network shared with the Mac that allows device-to-device traffic. With the phone connected, desktop **Tools → Install Network Certificate** writes a `.crt` copy of the CA named after its common name (such as `Droid CUA Root fbd877ab.crt`, in `~/.droid-cua/network/android/`), copies it to the phone's Downloads folder, and shows the steps: Settings → Security → Encryption & credentials → Install a certificate → CA certificate (names vary by vendor), set Wi-Fi → Edit network → Proxy → Manual to the Mac address and port `8765` that Droid prints, then restart the tested app. If the copy fails, the dialog names the local file for the user to copy. Since Android 7, apps trust user CAs only when their network security config allows it (`<certificates src="user"/>` or debug overrides), so debug and QA builds usually work and Play Store builds usually do not; Chrome trusts user CAs. Rooted-phone system trust is not supported. Relay these steps; never change the phone's certificates or settings yourself, and remind the user to turn the proxy off after testing.
+
 ## Web
 
 Droid CUA automatically discovers Chrome or Edge on macOS and Windows. Check the standard application locations, then run the requested test with `--target web --browser <chrome|edge> --session-mode fresh`. A successful Playwright launch is the runtime verification; do not create a persistent setup-only test.

package/skill/droid-cua/references/running-and-healing.md

@@ -22,7 +22,11 @@ Include `--report reports/<test-name>.html` for normal test runs unless the user
 
 For macOS and Windows desktop tests in application mode, the desktop app shows a system notice for three seconds before Droid takes control. The three-second delay is fixed; once the test starts, use Stop in Droid to end it. Avoid using the mouse or keyboard during the run. Droid brings the selected target window to the foreground before the first capture. When the run ends, the target stays in front and a second system notice says Droid has finished controlling the desktop. Open Droid to review the result. Some Windows apps return an all-black window capture; Droid brings the target back to the foreground before cropping the visible desktop to its visible frame, excluding the invisible Windows resize border. The fallback logs an all-black capture warning and crops before resizing to preserve detail. A visible-frame lookup warning means Droid is using the outer window bounds, which may include invisible resize borders. Keep the target visible and unobstructed on the primary display. In accessibility input mode, bring the target to the foreground yourself if the fallback requests it; Droid does not focus it for screenshots. If a screenshot shows another app or black off-screen edges, check whether the target could be focused and fully displayed before changing the `.dcua` instructions.
 
-The local network proxy is off by default. Use `--network-proxy` only when the user asks for local mobile proxy forwarding and has prepared device routing. This flag starts an idle forwarding listener; it does not capture traffic or enable network assertions. Use `--capture-network` only when the user asks for captured traffic or network assertions for local Chrome, Edge, iOS Simulator or Android Emulator tests. It writes one JSONL log per test, beside `--report` output when enabled or under `logs/` otherwise. For mobile capture it starts the proxy; the active CA must exist and the device must trust it. Configure mobile proxy routing manually before the run. Manual setup and cleanup are the accepted V1 workflow. Clear that routing after use; if Droid exits or crashes, restart it or clear the proxy to restore connectivity. Captures stop recording at 100 MiB with a CAPTURE_LIMIT marker while traffic continues forwarding. Treat that partial artifact as incomplete evidence; live queries cannot establish absence after the limit. Capture is best effort and WebSocket messages are unsupported. Captures may contain credentials or sensitive data despite partial filtering, so do not print their contents or share the artifact without the user's direction. Report the printed log path and capture health. Network-enabled runs expose `query_network` for focused questions and cross-request assertions; its helper answers include flow references. Distinguish an application mismatch from an assertion that could not be established because capture evidence was insufficient. Absence checks need a completed observation window and working capture evidence; never claim that no request occurred solely because none was captured.
+The local network proxy is off by default. Use `--network-proxy` only when the user asks for local mobile proxy forwarding and has prepared device routing. This flag starts an idle forwarding listener; it does not capture traffic or enable network assertions. Use `--capture-network` only when the user asks for captured traffic or network assertions for local Chrome, Edge, iPhone, iOS Simulator, Android phone or Android Emulator tests. It writes one JSONL log per test, beside `--report` output when enabled or under `logs/` otherwise. For mobile capture it starts the proxy; the active CA must exist and the device must trust it. Configure mobile proxy routing manually before the run. Manual setup and cleanup are the accepted V1 workflow. Clear that routing after use; if Droid exits or crashes, restart it or clear the proxy to restore connectivity. Captures stop recording at 100 MiB with a CAPTURE_LIMIT marker while traffic continues forwarding. Treat that partial artifact as incomplete evidence; live queries cannot establish absence after the limit. Capture is best effort and WebSocket messages are unsupported. Captures may contain credentials or sensitive data despite partial filtering, so do not print their contents or share the artifact without the user's direction. Report the printed log path and capture health. Network-enabled runs expose `query_network` for focused questions and cross-request assertions; its helper answers include flow references. Distinguish an application mismatch from an assertion that could not be established because capture evidence was insufficient. Absence checks need a completed observation window and working capture evidence; never claim that no request occurred solely because none was captured.
+
+For a local iPhone (`--avd ios-device:<udid|auto>`), the proxy listens on all Mac addresses and the CLI prints the line to relay, such as `On the iPhone, set Wi-Fi → Configure Proxy → Manual: server 192.168.1.23, port 8765.` If it fails because the Mac has no network address an iPhone can reach, ask the user to join the Mac and iPhone to the same Wi-Fi network. "No traffic observed" on an iPhone usually means its proxy is not set, or the Wi-Fi blocks device-to-device traffic; "no requests were decrypted" means the Droid CA is not installed with full trust on the iPhone or the app pins its certificates. Pinned apps cannot be decrypted; report that rather than retrying.
+
+A physical Android phone connected over ADB (any serial other than `emulator-<port>`) works the same way: the CLI prints a line such as `On the Android phone, set Wi-Fi → Edit network → Proxy → Manual: hostname 192.168.1.23, port 8765.` to relay. "No requests were decrypted" on an Android phone usually means the Droid CA is not installed as a user CA certificate, or the app's network security config does not trust user CAs (common for Play Store builds; debug and QA builds usually opt in). Report that rather than retrying.
 
 Local Chrome and Edge capture through Playwright; no certificate or proxy setup is needed. Keep the same assertions, query tool and report workflow. Capture begins at run start and includes frames and popups in that browser context. CLI `--url` navigation is captured. Earlier traffic from an already-open page is not recovered: include navigation in the test when its initial load matters, rather than silently reloading or changing the browser profile. Browser capture observes normal cache and service-worker behavior. Worker-originated requests and responses served by a worker are identified in query metadata; an observed exchange is not proof of a new server request. Pending or unavailable bodies remain incomplete evidence. Cloud browsers, WebSockets, streaming-message inspection and HAR export are outside this capture support. A browser run does not depend on the mobile proxy being available.
 
@@ -44,6 +48,9 @@ droid-cua run tests/example.dcua --avd avd:<avd-name> --config ci/droid-cua.json
 # iOS Simulator
 droid-cua run tests/example.dcua --llm-provider loadmill --cua-model loadmill-pulse --platform ios --avd "<simulator-name>" --debug --report reports/example.html
 
+# iPhone connected by USB (run `droid-cua ios-device check` first)
+droid-cua run tests/example.dcua --llm-provider loadmill --cua-model loadmill-pulse --avd ios-device:<udid> --debug --report reports/example.html
+
 # Local web
 droid-cua run tests/example.dcua --llm-provider loadmill --cua-model loadmill-pulse --target web --browser chrome --session-mode fresh --debug --report reports/example.html
 
@@ -62,6 +69,8 @@ droid-cua run tests/auth/login.dcua tests/checkout/purchase.dcua admin/refund.dc
 
 Use `.ipa` and `--platform ios` for supported cloud iOS runs. Preserve existing config flags rather than replacing them with defaults.
 
+For an iPhone connected by USB, confirm `droid-cua ios-device check` passes before the first run (see [onboarding-and-troubleshooting.md](onboarding-and-troubleshooting.md)). Use `--avd ios-device:<udid>` from the check's last line, or `ios-device:auto` when only one iPhone is connected; `--platform` is not needed. Add `--ios-team <TEAMID>` only when the user belongs to several paid Apple teams. There is no `--app` for a local iPhone: the test opens an app already installed on it. In the run plan, tell the user the test runs on their own iPhone with the apps and data already on it, and that they need to keep it unlocked and nearby. During the run, `Enter your passcode on the iPhone to allow automation` and `iPhone locked — unlock to continue` are waits for the user, not failures: tell the user right away and keep monitoring.
+
 ## Confirm the run with the user
 
 Before starting any test command, send the user a short, plain-language run plan and wait for explicit confirmation. Treat this as a product conversation, not a command preview. Do not infer that a request to run a test also confirms an automatically selected device, browser, or batch of tests. For an explicitly requested author-run-improve workflow, the plan may ask approval for the baseline and the evidence-driven edit/rerun and confidence runs needed to reach a readiness decision; follow [iterative-improvement.md](iterative-improvement.md).
@@ -138,7 +147,7 @@ Keep this retrospective concise and lead with the result and improvement. Do not
 ## Classify the first divergence
 
 1. **Setup or authentication**: missing/invalid provider credential, dependency, license, browser, or executable. Return to onboarding and rerun only the failed check.
-2. **Target connectivity**: no device, unauthorized/offline ADB state, unavailable simulator, cloud credential/device/app problem, or lost session. Restore the same target, then rerun.
+2. **Target connectivity**: no device, unauthorized/offline ADB state, unavailable simulator, iPhone unplugged/untrusted/locked or its helper app not starting, cloud credential/device/app problem, or lost session. Restore the same target (for an iPhone, rerun `droid-cua ios-device check`), then rerun.
 3. **Test ambiguity or stale test knowledge**: instruction has multiple interpretations, relies on an unstable label, lacks a starting condition, or context contradicts the visible product. A minimal test/context correction is allowed.
 4. **Application regression**: the app crashes, displays an error, violates an explicit requirement, or consistently fails a stable assertion after correct setup. Stop and report a bug with evidence.
 5. **Transient execution**: temporary network, service, model, or timing failure without evidence of a deterministic product/test issue. Retry the unchanged targeted test once.