@houwert/conductor 0.6.0 → 0.7.1

package/dist/daemon/client.js

@@ -19,20 +19,36 @@ const verbose_js_1 = require("../verbose.js");
 const bootstrap_js_1 = require("../drivers/bootstrap.js");
 const STARTUP_POLL_MS = 200;
 const STARTUP_MAX_WAIT_MS = 10000;
-async function socketExists(sessionName) {
+async function fetchStatus(sessionName) {
     return new Promise((resolve) => {
         const req = http_1.default.get({ socketPath: (0, protocol_js_1.socketPath)(sessionName), path: '/status' }, (res) => {
-            res.resume();
-            resolve(res.statusCode === 200);
+            if (res.statusCode !== 200) {
+                res.resume();
+                resolve(null);
+                return;
+            }
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(Buffer.concat(chunks).toString('utf-8')));
+                }
+                catch {
+                    resolve(null);
+                }
+            });
         });
         req.setTimeout(500);
         req.on('timeout', () => {
             req.destroy();
-            resolve(false);
+            resolve(null);
         });
-        req.on('error', () => resolve(false));
+        req.on('error', () => resolve(null));
     });
 }
+async function socketExists(sessionName) {
+    return (await fetchStatus(sessionName)) !== null;
+}
 async function waitForDaemon(sessionName) {
     const deadline = Date.now() + STARTUP_MAX_WAIT_MS;
     while (Date.now() < deadline) {
@@ -42,9 +58,61 @@ async function waitForDaemon(sessionName) {
     }
     return false;
 }
+/**
+ * Wait until a process with the given PID is no longer running.
+ * Uses `process.kill(pid, 0)` which throws if the process is gone.
+ */
+async function waitForProcessExit(pid, timeoutMs = 5000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            return;
+        }
+        await new Promise((r) => setTimeout(r, 50));
+    }
+}
+/**
+ * True when the running daemon's CDP attachment matches the current process's
+ * `CONDUCTOR_CDP_URL` / `CONDUCTOR_CDP_TARGET_ID` env. A mismatch means the
+ * daemon would control the wrong browser (e.g. a standalone Playwright
+ * instance when the caller expects to drive an embedded webview), so the
+ * daemon must be restarted with the correct env.
+ */
+function daemonMatchesCdpEnv(status) {
+    const expectedCdpUrl = process.env.CONDUCTOR_CDP_URL ?? '';
+    const expectedCdpTargetId = process.env.CONDUCTOR_CDP_TARGET_ID ?? '';
+    const actualCdpUrl = status.cdpUrl ?? '';
+    const actualCdpTargetId = status.cdpTargetId ?? '';
+    return actualCdpUrl === expectedCdpUrl && actualCdpTargetId === expectedCdpTargetId;
+}
 async function startDaemon(sessionName = 'default') {
-    if (await socketExists(sessionName))
-        return true;
+    const existing = await fetchStatus(sessionName);
+    if (existing) {
+        if (daemonMatchesCdpEnv(existing))
+            return true;
+        (0, verbose_js_1.log)(`daemon [${sessionName}] CDP env mismatch ` +
+            `(daemon cdpUrl="${existing.cdpUrl ?? ''}" targetId="${existing.cdpTargetId ?? ''}", ` +
+            `env cdpUrl="${process.env.CONDUCTOR_CDP_URL ?? ''}" targetId="${process.env.CONDUCTOR_CDP_TARGET_ID ?? ''}") — restarting`);
+        // Capture the PID before stopDaemon removes the pidfile so we can wait
+        // for the old process to actually exit before respawning. Otherwise the
+        // old daemon's cleanup handler may unlink the new daemon's socket.
+        let oldPid;
+        try {
+            const raw = fs_1.default.readFileSync((0, protocol_js_1.pidFile)(sessionName), 'utf-8').trim();
+            const n = parseInt(raw, 10);
+            if (!isNaN(n))
+                oldPid = n;
+        }
+        catch {
+            /* no pid — continue */
+        }
+        await stopDaemon(sessionName);
+        if (oldPid !== undefined)
+            await waitForProcessExit(oldPid);
+    }
     const serverScript = path_1.default.join(__dirname, 'server.js');
     (0, verbose_js_1.log)(`daemon [${sessionName}] not running — spawning ${serverScript}`);
     const child = (0, child_process_1.spawn)(process.execPath, [serverScript, sessionName], {

package/dist/daemon/server.js

@@ -25,6 +25,22 @@ const web_server_js_1 = require("./web-server.js");
 const log_collector_js_1 = require("./log-collector.js");
 const session_js_1 = require("../session.js");
 const sessionName = process.argv[2] ?? 'default';
+/**
+ * CDP URL for connecting to an external browser (e.g. Stagehand's embedded
+ * webview). When set, the web driver attaches via Playwright's connectOverCDP
+ * instead of launching its own browser.
+ *
+ * Set by the host IDE (Stagehand) via the agent subprocess environment.
+ */
+const cdpUrl = process.env.CONDUCTOR_CDP_URL || undefined;
+/**
+ * Optional CDP target ID to pick a specific page when the host app exposes
+ * multiple webviews over one CDP endpoint (e.g. one per workspace in
+ * Stagehand). When set, the web driver finds the page whose underlying
+ * `Target.targetId` matches and attaches to it, instead of falling back to
+ * URL heuristics.
+ */
+const cdpTargetId = process.env.CONDUCTOR_CDP_TARGET_ID || undefined;
 const SOCKET_PATH = (0, protocol_js_1.socketPath)(sessionName);
 const PID_FILE = (0, protocol_js_1.pidFile)(sessionName);
 const LOG_FILE = (0, protocol_js_1.logFile)(sessionName);
@@ -75,7 +91,7 @@ async function ensureDriverRunning() {
                 await (0, bootstrap_js_1.startTvOSDriver)(sessionName, driverPort, /* dismissAfterLaunch */ false);
             }
             else if (driverPlatform === 'web') {
-                await (0, web_server_js_1.startWebServer)(driverPort, (0, bootstrap_js_1.webBrowserName)(sessionName), dlog);
+                await (0, web_server_js_1.startWebServer)(driverPort, (0, bootstrap_js_1.webBrowserName)(sessionName), dlog, cdpUrl, cdpTargetId);
             }
             else {
                 await (0, bootstrap_js_1.startAndroidDriver)(sessionName, driverPort);
@@ -96,6 +112,7 @@ async function main() {
     fs_1.default.mkdirSync(path_1.default.dirname(PID_FILE), { recursive: true });
     fs_1.default.writeFileSync(PID_FILE, String(process.pid));
     dlog(`daemon started pid=${process.pid} session=${sessionName}`);
+    dlog(`env CONDUCTOR_CDP_URL=${cdpUrl ?? '<unset>'} CONDUCTOR_CDP_TARGET_ID=${cdpTargetId ?? '<unset>'}`); // kept intentionally — useful for future diagnosis of CDP attachment issues
     // Remove stale socket
     try {
         fs_1.default.unlinkSync(SOCKET_PATH);
@@ -212,7 +229,13 @@ async function main() {
         resetIdleTimer();
         const parsed = url_1.default.parse(req.url ?? '/', true);
         if (req.method === 'GET' && parsed.pathname === '/status') {
-            jsonResponse(res, { ok: true, platform: driverPlatform, driverPort });
+            jsonResponse(res, {
+                ok: true,
+                platform: driverPlatform,
+                driverPort,
+                cdpUrl: cdpUrl ?? null,
+                cdpTargetId: cdpTargetId ?? null,
+            });
             return;
         }
         if (req.method === 'GET' && parsed.pathname === '/logs') {
@@ -277,7 +300,9 @@ async function main() {
                         await (0, bootstrap_js_1.installDriver)(sessionName);
                         dlog(`Driver installation complete`);
                     }
-                    else if (platform === 'web') {
+                    else if (platform === 'web' && !cdpUrl) {
+                        // Only install Playwright browser when launching standalone.
+                        // In CDP mode we attach to the host app's browser (e.g. Electron).
                         const browser = (0, bootstrap_js_1.webBrowserName)(sessionName);
                         await (0, bootstrap_js_1.ensurePlaywrightBrowser)(browser, dlog);
                     }
@@ -291,7 +316,7 @@ async function main() {
                             await (0, bootstrap_js_1.startTvOSDriver)(sessionName, driverPort, /* dismissAfterLaunch */ true);
                         }
                         else if (platform === 'web') {
-                            await (0, web_server_js_1.startWebServer)(driverPort, (0, bootstrap_js_1.webBrowserName)(sessionName), dlog);
+                            await (0, web_server_js_1.startWebServer)(driverPort, (0, bootstrap_js_1.webBrowserName)(sessionName), dlog, cdpUrl, cdpTargetId);
                         }
                         else {
                             await (0, bootstrap_js_1.startAndroidDriver)(sessionName, driverPort);

package/dist/daemon/web-server.js

@@ -426,19 +426,107 @@ let _browser = null;
 let _context = null;
 let _page = null;
 let _server = null;
-async function startWebServer(port, browserName = 'chromium', dlog = () => { }) {
-    const browserType = browserName === 'firefox' ? playwright_core_1.firefox : browserName === 'webkit' ? playwright_core_1.webkit : playwright_core_1.chromium;
-    dlog(`Launching ${browserName} browser...`);
-    _browser = await browserType.launch({
-        headless: false,
-        args: browserName === 'chromium' ? ['--disable-search-engine-choice-screen'] : undefined,
-    });
-    _context = await _browser.newContext({
-        viewport: DEFAULT_VIEWPORT,
-    });
-    _page = await _context.newPage();
-    attachConsoleListeners(_page);
-    dlog(`Browser ready, page created`);
+/**
+ * True when connected to an external browser via CDP (e.g. Stagehand's
+ * embedded webview). In this mode we must NOT close the browser on shutdown
+ * — we only disconnect.
+ */
+let _cdpMode = false;
+async function startWebServer(port, browserName = 'chromium', dlog = () => { }, cdpUrl, cdpTargetId) {
+    if (cdpUrl) {
+        // ── CDP mode: attach to an existing browser (e.g. Electron webview) ───
+        dlog(`Connecting to existing browser via CDP: ${cdpUrl}`);
+        _browser = await playwright_core_1.chromium.connectOverCDP(cdpUrl);
+        _cdpMode = true;
+        // Use an existing context and page. The host app (e.g. Stagehand) already
+        // created them — we just take a handle.
+        const contexts = _browser.contexts();
+        if (contexts.length === 0) {
+            throw new Error('No browser contexts found via CDP — is the webview loaded?');
+        }
+        // Match the specific CDP target ID provided by the host app. Required —
+        // with multiple pages sharing one CDP port (Electron host window, webviews,
+        // DevTools), "guess the right one" is a foot-gun that ends in navigating
+        // the wrong window. If no targetId is supplied, or the supplied one can't
+        // be resolved to a Playwright Page, we throw rather than attaching to an
+        // arbitrary target.
+        if (!cdpTargetId) {
+            throw new Error('CDP mode requires CONDUCTOR_CDP_TARGET_ID — set it to the specific page target to control.');
+        }
+        dlog(`Selecting CDP target by ID: ${cdpTargetId}`);
+        const pageDiag = [];
+        outer: for (const ctx of contexts) {
+            for (const page of ctx.pages()) {
+                try {
+                    const session = await ctx.newCDPSession(page);
+                    const info = (await session.send('Target.getTargetInfo'));
+                    await session.detach().catch(() => { });
+                    const t = info.targetInfo;
+                    pageDiag.push(`page targetId=${t?.targetId ?? '?'} type=${t?.type ?? '?'} url=${t?.url ?? page.url()}`);
+                    if (t?.targetId === cdpTargetId) {
+                        _context = ctx;
+                        _page = page;
+                        break outer;
+                    }
+                }
+                catch (err) {
+                    pageDiag.push(`page url=${page.url()} getTargetInfo failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        if (!_page) {
+            // Enumerate all CDP targets to produce an actionable error — in
+            // particular so we can distinguish "wrong targetId" from "target exists
+            // but Playwright can't see it as a Page" (the latter happens when the
+            // host embeds content as a <webview> guest — type="webview" in CDP —
+            // rather than as a top-level page).
+            let diagExtra = '';
+            let expectedType;
+            try {
+                const browserSession = await _browser.newBrowserCDPSession();
+                const all = (await browserSession.send('Target.getTargets'));
+                await browserSession.detach().catch(() => { });
+                const enumerated = all.targetInfos
+                    ?.map((t) => `  - ${t.type.padEnd(10)} ${t.targetId.slice(0, 8)} ${t.url}`)
+                    .join('\n') ?? '(none)';
+                const expected = all.targetInfos?.find((t) => t.targetId === cdpTargetId);
+                expectedType = expected?.type;
+                diagExtra =
+                    `\nPages visible to Playwright (${pageDiag.length}):\n` +
+                        pageDiag.map((l) => `  - ${l}`).join('\n') +
+                        `\nAll CDP targets (${all.targetInfos?.length ?? 0}):\n${enumerated}\n` +
+                        (expected
+                            ? `Requested target exists but type="${expected.type}" — Playwright only surfaces type="page".`
+                            : `Requested target not present in Target.getTargets — stale or wrong ID.`);
+            }
+            catch (err) {
+                diagExtra = `\nTarget enumeration failed: ${err instanceof Error ? err.message : String(err)}`;
+            }
+            dlog(`CDP target id ${cdpTargetId} not matched by any Playwright Page.${diagExtra}`);
+            throw new Error(`CDP target ${cdpTargetId} not reachable as a Playwright Page` +
+                (expectedType
+                    ? ` (exists as type="${expectedType}" — Playwright only surfaces type="page")`
+                    : ` (not in target list)`));
+        }
+        attachConsoleListeners(_page);
+        dlog(`CDP connected — page: ${_page.url()}`);
+    }
+    else {
+        // ── Standalone mode: launch a fresh browser ───────────────────────────
+        const browserType = browserName === 'firefox' ? playwright_core_1.firefox : browserName === 'webkit' ? playwright_core_1.webkit : playwright_core_1.chromium;
+        dlog(`Launching ${browserName} browser...`);
+        _browser = await browserType.launch({
+            headless: false,
+            args: browserName === 'chromium' ? ['--disable-search-engine-choice-screen'] : undefined,
+        });
+        _context = await _browser.newContext({
+            viewport: DEFAULT_VIEWPORT,
+        });
+        _page = await _context.newPage();
+        attachConsoleListeners(_page);
+        dlog(`Browser ready, page created`);
+        _cdpMode = false;
+    }
     _server = http_1.default.createServer(async (req, res) => {
         try {
             await handleRequest(req, res, dlog);
@@ -462,18 +550,38 @@ async function stopWebServer() {
         _server.close();
         _server = null;
     }
-    if (_page) {
-        await _page.close().catch(() => { });
+    if (_cdpMode) {
+        // CDP mode: we don't own the browser — just release our handles.
+        // Do NOT close the page, context, or browser.
         _page = null;
-    }
-    if (_context) {
-        await _context.close().catch(() => { });
         _context = null;
+        if (_browser) {
+            // Playwright's connectOverCDP browser supports disconnect() but not close().
+            try {
+                _browser.close().catch(() => { });
+            }
+            catch {
+                /* not all CDP browsers support close gracefully */
+            }
+            _browser = null;
+        }
     }
-    if (_browser) {
-        await _browser.close().catch(() => { });
-        _browser = null;
+    else {
+        // Standalone mode: we launched the browser, so tear it all down.
+        if (_page) {
+            await _page.close().catch(() => { });
+            _page = null;
+        }
+        if (_context) {
+            await _context.close().catch(() => { });
+            _context = null;
+        }
+        if (_browser) {
+            await _browser.close().catch(() => { });
+            _browser = null;
+        }
     }
+    _cdpMode = false;
 }
 /** Playwright / CDP errors when the tab, context, or session died but our JS refs still exist. */
 function isClosedLikeError(err) {
@@ -483,20 +591,40 @@ function isClosedLikeError(err) {
 /**
  * Drop the context and open a fresh one. Used when newPage/goto fails after the user closed
  * the last tab (Chromium can quit the window) or the CDP target is gone while isConnected stays true.
+ *
+ * In CDP mode, we can't create new contexts — the host app owns the browser.
+ * Instead we try to re-acquire an existing context/page.
  */
 async function recreateBrowserContext(dlog) {
     dlog?.('Web driver: recreating browser context');
-    if (_context) {
-        await _context.close().catch(() => { });
-        _context = null;
-    }
-    _page = null;
     if (!_browser) {
         throw new Error('No page available');
     }
     if (!_browser.isConnected()) {
         throw new Error('Browser has been closed. Restart the web driver (e.g. conductor daemon-start --device web).');
     }
+    if (_cdpMode) {
+        // In CDP mode, try to re-acquire a page from existing contexts.
+        _page = null;
+        _context = null;
+        const contexts = _browser.contexts();
+        for (const ctx of contexts) {
+            const pages = ctx.pages();
+            const candidate = pages.find((p) => !p.isClosed());
+            if (candidate) {
+                _context = ctx;
+                _page = candidate;
+                attachConsoleListeners(_page);
+                return;
+            }
+        }
+        throw new Error('No live pages found via CDP — is the webview still open?');
+    }
+    if (_context) {
+        await _context.close().catch(() => { });
+        _context = null;
+    }
+    _page = null;
     _context = await _browser.newContext({
         viewport: DEFAULT_VIEWPORT,
     });
@@ -629,6 +757,10 @@ async function handleRequest(req, res, dlog) {
                 jsonResponse(res, { url: (await getPage(dlog)).url() });
                 return;
             }
+            case '/runningApp': {
+                jsonResponse(res, { runningAppBundleId: (await getPage(dlog)).url() });
+                return;
+            }
             case '/title': {
                 jsonResponse(res, { title: await (await getPage(dlog)).title() });
                 return;
@@ -779,10 +911,6 @@ async function handleRequest(req, res, dlog) {
                 jsonResponse(res, { ok: true });
                 return;
             }
-            case '/runningApp': {
-                jsonResponse(res, { runningAppBundleId: (await getPage(dlog)).url() });
-                return;
-            }
             case '/eraseText': {
                 const count = body['count'] ?? 50;
                 const p = await getPage(dlog);

package/dist/index.js

@@ -46,6 +46,9 @@ const delete_device_js_1 = require("./commands/delete-device.js");
 const logs_js_1 = require("./commands/logs.js");
 const device_picker_js_1 = require("./device-picker.js");
 const update_check_js_1 = require("./update-check.js");
+const pkg_root_js_1 = require("./pkg-root.js");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const COMMAND_HELP = {
     'start-device': start_device_js_1.HELP,
     'delete-device': delete_device_js_1.HELP,
@@ -96,6 +99,7 @@ const OPTIONS_HELP = `Options:
   --platform <p>    Filter to devices of this platform (ios, android, tvos, web)
   --json            Output as machine-readable JSON
   --verbose, -v     Log daemon calls, fallbacks, and raw output
+  --version, -V     Print version number
   --help, -h        Show this help`;
 const HELP = `Usage: conductor <command> [args] [options]
 
@@ -109,6 +113,7 @@ async function main() {
         boolean: [
             'json',
             'help',
+            'version',
             'clear',
             'list',
             'verbose',
@@ -155,12 +160,18 @@ async function main() {
             'metro-port',
             'level',
         ],
-        alias: { h: 'help', v: 'verbose' },
+        alias: { h: 'help', v: 'verbose', V: 'version' },
     });
     if (argv['verbose'])
         (0, verbose_js_1.setVerbose)(true);
     const [command, ...rest] = argv._;
     const opts = { json: argv['json'] };
+    if (argv['version']) {
+        const pkgRoot = (0, pkg_root_js_1.findPkgRoot)(__dirname);
+        const pkg = JSON.parse(fs_1.default.readFileSync(path_1.default.join(pkgRoot, 'package.json'), 'utf-8'));
+        console.log(pkg.version);
+        process.exit(0);
+    }
     // Handle help and unknown commands before device resolution —
     // no point prompting for a device if we're just printing help or erroring out.
     if (!command || argv['help']) {

package/package.json

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

package/skills/conductor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: conductor
-version: 0.6.0
+version: 0.7.1
 description: "Token-efficient CLI for mobile UI testing (iOS simulator + Android emulator), designed for AI agents"
 metadata.openclaw:
   category: service

package/skills/skills.yaml

@@ -3,6 +3,6 @@ skills:
     path: conductor/SKILL.md
     description: "Token-efficient CLI for mobile UI testing, designed for AI agents"
     category: service
-    version: 0.6.0
+    version: 0.7.1
     requires:
       bins: [conductor]