@houwert/conductor 0.14.0 → 0.16.0

package/dist/commands/memory.js

@@ -37,12 +37,29 @@ async function resolveDeviceId(sessionName) {
     const session = await (0, session_js_1.getSession)(sessionName);
     return session.deviceId ?? (await (0, runner_js_1.detectFirstDevice)());
 }
-async function resolveAppId(explicit, sessionName, deviceId) {
+async function resolveAppId(explicit, sessionName, deviceId, platform) {
     if (explicit)
         return explicit;
     // No arg: always resolve from the live foreground app, not the session file.
     // The session's appId reflects the last `launch-app` call, which can be stale
     // if the user switched apps on the device by other means.
+    //
+    // On Android, foreground-app detection only needs `adb shell dumpsys` — going
+    // through getDriver() would force the gRPC daemon to start (and require the
+    // driver APK to be installed), which is wasteful for a read-only memory dump.
+    if (platform === 'android') {
+        const dump = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('adb'), ['-s', deviceId, 'shell', 'dumpsys', 'activity', 'activities'], { env: (0, sdk_js_1.androidSpawnEnv)() });
+        if (dump.success) {
+            // Different Android versions print this differently:
+            //   API 28-:  mResumedActivity: ActivityRecord{... pkg/.Activity ...}
+            //   API 29+:  topResumedActivity=ActivityRecord{... pkg/.Activity ...}
+            //             ResumedActivity:    ActivityRecord{... pkg/.Activity ...}
+            const m = dump.stdout.match(/(?:m|top)?ResumedActivity[=:].*?([a-zA-Z][a-zA-Z0-9_]*(?:\.[a-zA-Z][a-zA-Z0-9_]*)+)\//);
+            if (m)
+                return m[1];
+        }
+        return undefined;
+    }
     try {
         const driver = await (0, runner_js_1.getDriver)(sessionName);
         if (driver instanceof android_js_1.AndroidDriver)
@@ -1104,13 +1121,17 @@ async function memory(appIdArg, opts = {}, sessionName = 'default', memOpts = {}
         report = await collectWeb(deviceId, sessionName, memOpts);
     }
     else {
-        const appId = await resolveAppId(appIdArg, sessionName, deviceId);
+        const appId = await resolveAppId(appIdArg, sessionName, deviceId, platform);
         if (platform === 'android') {
             report = await collectAndroid(deviceId, appId, memOpts);
         }
         else {
             report = await collectIOS(deviceId, platform, appId, memOpts);
         }
+        if (!appId) {
+            report.notes ?? (report.notes = []);
+            report.notes.push('No foreground app detected — pass an app id (e.g. `conductor memory com.example.app --all`) to get per-app memory, objects, and leaks.');
+        }
     }
     report.capturedAt = new Date().toISOString();
     // Diff current report against a saved snapshot.

package/dist/commands/screenshot.js

@@ -5,19 +5,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
 exports.screenshot = screenshot;
-exports.HELP = `  take-screenshot [--output <path>]    Take screenshot`;
+exports.HELP = `  take-screenshot [--output <path>] [--full-page]
+                                       Take screenshot (--full-page: web only, capture entire scrollable page)`;
 const path_1 = __importDefault(require("path"));
 const promises_1 = __importDefault(require("fs/promises"));
 const runner_js_1 = require("../runner.js");
 const output_js_1 = require("../output.js");
-async function screenshot(outputPath, opts = {}, sessionName = 'default') {
+async function screenshot(outputPath, opts = {}, sessionName = 'default', fullPage = false) {
     const timestamp = Date.now();
     const defaultName = `screenshot-${timestamp}.png`;
     const resolvedPath = outputPath
         ? path_1.default.resolve(outputPath)
         : path_1.default.resolve(process.cwd(), defaultName);
     const result = await (0, runner_js_1.runDirect)(async (driver) => {
-        const buf = await driver.screenshot();
+        const buf = await driver.screenshot({ fullPage });
         await promises_1.default.writeFile(resolvedPath, buf);
     }, sessionName);
     if (result.success) {

package/dist/commands/start-device.js

@@ -4,13 +4,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
+exports.pickAndroidArch = pickAndroidArch;
+exports.parseInstalledSystemImages = parseInstalledSystemImages;
+exports.pickSystemImage = pickSystemImage;
+exports.buildAvdmanagerCreateArgs = buildAvdmanagerCreateArgs;
 exports.startDevice = startDevice;
 exports.HELP = `  start-device
     --platform <ios|android|tvos|web> Boot a simulator/emulator, or start the web driver (Playwright)
     --os-version <n>                  iOS/tvOS version (e.g. 18) or Android API level (e.g. 33)
-    --avd <name>                      Android AVD name (default: first available)
+    --avd <name>                      Android AVD name (default: first available; created if missing + --device-type)
     --name <name>                     Set a custom name on the device after creation (iOS/tvOS/web)
-    --device-type <name>              iOS/tvOS device type (e.g. "iPhone 16 Pro", "Apple TV 4K"); creates if needed
+    --device-type <name>              iOS/tvOS device type (e.g. "iPhone 16 Pro", "Apple TV 4K") or
+                                      Android device profile (e.g. "pixel_7"); creates if needed
+    --system-image <id>               Android only: override auto-picked system image
+                                      (e.g. "system-images;android-34;google_apis;arm64-v8a")
     --browser <chromium|firefox|webkit> Web only: which Playwright browser to launch (default: chromium)`;
 const fs_1 = __importDefault(require("fs"));
 const child_process_1 = require("child_process");
@@ -390,6 +397,9 @@ async function startTvOS(osVersion, opts, name, deviceType) {
     return 0;
 }
 // ── Android ───────────────────────────────────────────────────────────────────
+// TODO: Replace bare command names with the resolver from `android-sdk-path-resolver-68477d`
+// once it lands on main. For now we rely on `emulator`/`adb`/`avdmanager`/`sdkmanager`
+// being on PATH.
 async function listAVDs() {
     const result = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('emulator'), ['-list-avds'], {
         env: (0, sdk_js_1.androidSpawnEnv)(),
@@ -401,6 +411,139 @@ async function listAVDs() {
         .map((l) => l.trim())
         .filter(Boolean);
 }
+/** Pick the Android system-image arch tag based on the host CPU. */
+function pickAndroidArch(arch = process.arch) {
+    return arch === 'arm64' ? 'arm64-v8a' : 'x86_64';
+}
+/**
+ * Parse `sdkmanager --list_installed` (or --list) output, returning installed
+ * system-image package paths like "system-images;android-34;google_apis;arm64-v8a".
+ */
+function parseInstalledSystemImages(stdout) {
+    const images = [];
+    for (const rawLine of stdout.split('\n')) {
+        const line = rawLine.trim();
+        if (!line.startsWith('system-images;'))
+            continue;
+        // Format is "<path> | <version> | <description> | <location>" with leading whitespace
+        const path = line.split(/[|\s]+/)[0];
+        if (path && !images.includes(path))
+            images.push(path);
+    }
+    return images;
+}
+/**
+ * Pick the best installed system image matching the requested API level and arch.
+ * Prefers `google_apis` over `default` (no Play store dependency on Apple Silicon
+ * where Play images often lack arm64). Returns undefined if no match.
+ */
+function pickSystemImage(installed, apiLevel, arch) {
+    const filtered = installed.filter((img) => {
+        const parts = img.split(';');
+        // parts: ["system-images", "android-<api>", "<variant>", "<arch>"]
+        if (parts.length < 4)
+            return false;
+        if (parts[3] !== arch)
+            return false;
+        if (apiLevel && parts[1] !== `android-${apiLevel}`)
+            return false;
+        return true;
+    });
+    if (filtered.length === 0)
+        return undefined;
+    // Variant preference: google_apis > google_apis_playstore > default > others
+    const rank = (img) => {
+        const variant = img.split(';')[2];
+        if (variant === 'google_apis')
+            return 0;
+        if (variant === 'google_apis_playstore')
+            return 1;
+        if (variant === 'default')
+            return 2;
+        return 3;
+    };
+    filtered.sort((a, b) => {
+        const r = rank(a) - rank(b);
+        if (r !== 0)
+            return r;
+        // Then prefer higher API level
+        const ai = parseInt(a.split(';')[1].replace('android-', ''), 10) || 0;
+        const bi = parseInt(b.split(';')[1].replace('android-', ''), 10) || 0;
+        return bi - ai;
+    });
+    return filtered[0];
+}
+/** Build the avdmanager argv for AVD creation — pure, exported for tests. */
+function buildAvdmanagerCreateArgs(avdName, systemImage, deviceProfile) {
+    return ['create', 'avd', '-n', avdName, '-k', systemImage, '-d', deviceProfile];
+}
+async function listInstalledSystemImages() {
+    const result = await (0, runner_js_1.spawnCommand)('sdkmanager', ['--list_installed']);
+    if (!result.success) {
+        throw new Error(`sdkmanager --list_installed failed: ${result.stderr.trim() || result.stdout.trim()}`);
+    }
+    return parseInstalledSystemImages(result.stdout);
+}
+/** Run avdmanager create avd, piping "no\n" so it skips the custom hardware prompt. */
+async function spawnAvdmanagerCreate(args) {
+    await new Promise((resolve, reject) => {
+        const proc = (0, child_process_1.spawn)('avdmanager', args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        let stderr = '';
+        proc.stdout.on('data', () => {
+            /* discard */
+        });
+        proc.stderr.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        proc.on('error', (err) => reject(err));
+        proc.on('close', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`avdmanager exited ${code}: ${stderr.trim()}`));
+        });
+        proc.stdin.end('no\n');
+    });
+}
+async function createAndroidAVD(avdName, deviceProfile, apiLevel, systemImageOverride) {
+    const arch = pickAndroidArch();
+    let systemImage;
+    if (systemImageOverride) {
+        systemImage = systemImageOverride;
+    }
+    else {
+        let installed;
+        try {
+            installed = await listInstalledSystemImages();
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`Could not list installed Android system images (${msg}). ` +
+                `Ensure the Android SDK command-line tools are installed and on PATH.`);
+        }
+        const picked = pickSystemImage(installed, apiLevel, arch);
+        if (!picked) {
+            const apiHint = apiLevel ?? '34';
+            throw new Error(`No installed Android system image matches arch=${arch}` +
+                (apiLevel ? `, api=${apiLevel}` : '') +
+                `.\nInstall one with:\n  sdkmanager "system-images;android-${apiHint};google_apis;${arch}"`);
+        }
+        systemImage = picked;
+    }
+    const args = buildAvdmanagerCreateArgs(avdName, systemImage, deviceProfile);
+    try {
+        await spawnAvdmanagerCreate(args);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`Failed to create AVD "${avdName}": ${msg}`);
+    }
+    // Validate the AVD now appears in emulator -list-avds
+    const avds = await listAVDs();
+    if (!avds.includes(avdName)) {
+        throw new Error(`AVD "${avdName}" was not registered after creation (not in emulator -list-avds).`);
+    }
+}
 async function waitForAndroidBoot(avdName) {
     const deadline = Date.now() + ANDROID_BOOT_TIMEOUT_MS;
     const connectedBefore = new Set();
@@ -434,7 +577,7 @@ async function waitForAndroidBoot(avdName) {
     }
     throw new Error(`Android emulator (${avdName}) did not appear within ${ANDROID_BOOT_TIMEOUT_MS / 1000}s`);
 }
-async function startAndroid(avdName, opts) {
+async function startAndroid(avdName, opts, deviceType, osVersion, systemImage) {
     let avds;
     try {
         avds = await listAVDs();
@@ -443,13 +586,34 @@ async function startAndroid(avdName, opts) {
         (0, output_js_1.printError)(`Failed to list AVDs: ${e instanceof Error ? e.message : String(e)}`, opts);
         return 1;
     }
-    if (avds.length === 0) {
-        (0, output_js_1.printError)('No Android AVDs found. Create one in Android Studio → Device Manager.', opts);
+    let target = avdName ?? avds[0];
+    // If the requested AVD doesn't exist (or none exist) and a device profile was
+    // provided, create the AVD before booting.
+    const needsCreate = (avds.length === 0 || (avdName !== undefined && !avds.includes(avdName))) &&
+        deviceType !== undefined;
+    if (needsCreate) {
+        if (!avdName) {
+            (0, output_js_1.printError)('--avd <name> is required when creating an AVD with --device-type.', opts);
+            return 1;
+        }
+        console.log(`No AVD "${avdName}" found. Creating one with device profile "${deviceType}"...`);
+        try {
+            await createAndroidAVD(avdName, deviceType, osVersion, systemImage);
+        }
+        catch (e) {
+            (0, output_js_1.printError)(e instanceof Error ? e.message : String(e), opts);
+            return 1;
+        }
+        target = avdName;
+    }
+    else if (avds.length === 0) {
+        (0, output_js_1.printError)('No Android AVDs found. Pass --device-type <profile> --avd <name> to create one, ' +
+            'or create one in Android Studio → Device Manager.', opts);
         return 1;
     }
-    const target = avdName ?? avds[0];
-    if (!avds.includes(target)) {
-        (0, output_js_1.printError)(`AVD "${target}" not found. Available: ${avds.join(', ')}`, opts);
+    else if (!avds.includes(target)) {
+        (0, output_js_1.printError)(`AVD "${target}" not found. Available: ${avds.join(', ')}. ` +
+            `Pass --device-type to create it.`, opts);
         return 1;
     }
     console.log(`Launching emulator: ${target}...`);
@@ -524,7 +688,7 @@ async function startDevice(platform, opts, flags) {
         case 'tvos':
             return startTvOS(flags.osVersion, opts, flags.name, flags.deviceType);
         case 'android':
-            return startAndroid(flags.avd, opts);
+            return startAndroid(flags.avd, opts, flags.deviceType, flags.osVersion, flags.systemImage);
         case 'web':
             return startWebDriver(opts, flags.browser, flags.name);
         default:

package/dist/daemon/web-server.js

@@ -437,6 +437,24 @@ let _server = null;
 let _cdpMode = false;
 let _cdpPort = 0;
 let _pageTargetId = null;
+/**
+ * Default User-Agent applied to created contexts. Derived from the launched
+ * browser's UA with "HeadlessChrome" rewritten to "Chrome" so remote servers
+ * don't see automation/headless markers in the UA string.
+ */
+let _defaultUserAgent;
+async function deriveDefaultUserAgent(browser) {
+    try {
+        const tmpCtx = await browser.newContext();
+        const tmpPage = await tmpCtx.newPage();
+        const ua = await tmpPage.evaluate(() => globalThis.navigator.userAgent);
+        await tmpCtx.close().catch(() => { });
+        return ua.replace(/HeadlessChrome/g, 'Chrome');
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Find a free TCP port by briefly binding to port 0. */
 function findFreePort() {
     return new Promise((resolve, reject) => {
@@ -557,8 +575,10 @@ async function startWebServer(port, browserName = 'chromium', dlog = () => { },
                 ? [`--remote-debugging-port=${_cdpPort}`, '--disable-search-engine-choice-screen']
                 : undefined,
         });
+        _defaultUserAgent = await deriveDefaultUserAgent(_browser);
         _context = await _browser.newContext({
             viewport: DEFAULT_VIEWPORT,
+            userAgent: _defaultUserAgent,
         });
         _page = await _context.newPage();
         attachConsoleListeners(_page);
@@ -692,6 +712,7 @@ async function recreateBrowserContext(dlog) {
     _page = null;
     _context = await _browser.newContext({
         viewport: DEFAULT_VIEWPORT,
+        userAgent: _defaultUserAgent,
     });
     _page = await _context.newPage();
     attachConsoleListeners(_page);
@@ -791,7 +812,9 @@ async function handleRequest(req, res, dlog) {
                 return;
             }
             case '/screenshot': {
-                const buf = await (await getPage(dlog)).screenshot({ type: 'png' });
+                const fullPageRaw = parsedUrl.query.fullPage;
+                const fullPage = fullPageRaw === '1' || fullPageRaw === 'true';
+                const buf = await (await getPage(dlog)).screenshot({ type: 'png', fullPage });
                 res.writeHead(200, {
                     'Content-Type': 'image/png',
                     'Content-Length': buf.length,
@@ -1077,7 +1100,7 @@ async function handleRequest(req, res, dlog) {
                     await _context.close().catch(() => { });
                 _context = await _browser.newContext({
                     viewport: { width: vpWidth, height: vpHeight },
-                    userAgent: vpUserAgent,
+                    userAgent: vpUserAgent ?? _defaultUserAgent,
                     deviceScaleFactor: vpScaleFactor,
                     isMobile: vpIsMobile,
                     hasTouch: vpIsMobile,

package/dist/drivers/android.js

@@ -142,7 +142,7 @@ class AndroidDriver {
         const resp = await this.call('viewHierarchy', {});
         return resp.hierarchy;
     }
-    async screenshot() {
+    async screenshot(_opts = {}) {
         const resp = await this.call('screenshot', {});
         return Buffer.from(resp.bytes);
     }
@@ -203,7 +203,9 @@ class AndroidDriver {
     }
     async getForegroundApp() {
         const output = await this.adbOutput(['shell', 'dumpsys', 'activity', 'activities']);
-        const match = output.match(/mResumedActivity.*?([a-zA-Z][a-zA-Z0-9_]*(?:\.[a-zA-Z][a-zA-Z0-9_]*)+)\//);
+        // API 28- prints `mResumedActivity:`; API 29+ uses `ResumedActivity:` /
+        // `topResumedActivity=`. Accept all three so this works across versions.
+        const match = output.match(/(?:m|top)?ResumedActivity[=:].*?([a-zA-Z][a-zA-Z0-9_]*(?:\.[a-zA-Z][a-zA-Z0-9_]*)+)\//);
         if (!match)
             throw new Error('Could not determine foreground app');
         return match[1];

package/dist/drivers/ios.js

@@ -308,7 +308,7 @@ class IOSDriver {
         }
         return JSON.parse(data.toString('utf-8'));
     }
-    async screenshot() {
+    async screenshot(_opts = {}) {
         const { status, data } = await this.request('GET', '/screenshot');
         if (status < 200 || status >= 300) {
             throw new Error(`iOS driver screenshot failed (HTTP ${status})`);

package/dist/drivers/web.js

@@ -121,8 +121,9 @@ class WebDriver {
     async viewHierarchy() {
         return this.get('viewHierarchy');
     }
-    async screenshot() {
-        const { status, data } = await this.request('GET', '/screenshot');
+    async screenshot(opts = {}) {
+        const path = opts.fullPage ? '/screenshot?fullPage=1' : '/screenshot';
+        const { status, data } = await this.request('GET', path);
         if (status < 200 || status >= 300) {
             throw new Error(`Web driver screenshot failed (HTTP ${status})`);
         }

package/dist/index.js

@@ -162,6 +162,7 @@ async function main() {
             'name',
             'device-name',
             'device-type',
+            'system-image',
             'browser',
             'from',
             'to',
@@ -249,6 +250,7 @@ async function main() {
                 avd: argv['avd'],
                 name: argv['name'],
                 deviceType: argv['device-type'],
+                systemImage: argv['system-image'],
                 browser: argv['browser'],
             });
             break;
@@ -459,7 +461,8 @@ async function main() {
         }
         case 'take-screenshot': {
             const outPath = argv['output'];
-            exitCode = await (0, screenshot_js_1.screenshot)(outPath, opts, sessionName);
+            const fullPage = Boolean(argv['full-page']);
+            exitCode = await (0, screenshot_js_1.screenshot)(outPath, opts, sessionName, fullPage);
             break;
         }
         case 'capture-ui': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {