// CDP transport and session resolution. // // A backgrounded Chrome window never acknowledges Input.* commands: it waits // for a renderer frame that throttling does not produce, then times out after // exactly 5000ms. The event is delivered regardless. So input is fired without // awaiting a reply and paced by the caller's clock. // // Targets are discovered over the browser websocket, not over HTTP. Chrome and // Edge M144+ expose remote debugging through chrome://inspect without the // --remote-debugging-port flag. That server serves no /json/* routes: every // path returns 404 and a root websocket upgrade returns 403. Only // ws://127.0.0.1:/devtools/browser/ accepts a connection, and // DevToolsActivePort line 2 carries that path. import fs from 'node:fs'; import path from 'node:path'; import os from 'node:os'; import net from 'node:net'; import crypto from 'node:crypto'; import { spawn } from 'node:child_process'; import { fileURLToPath } from 'node:url'; // Deliberately no approve.mjs import. Approval belongs to daemon.mjs alone. import { safeCommand } from './audit.mjs'; import { pipeName, probe } from './daemon.mjs'; import { hasAgentBrowser } from './env.mjs'; const HOME = os.homedir(); const PROFILES = process.env.AGENT_HANDS_PROFILES || path.join(HOME, '.agent-browser-profiles'); // Default user data directories of browsers this machine did not launch. // Any Chromium fork works; this table only saves the user from typing a path. // --user-data-dir covers forks, portable installs and non-default locations. const CHANNELS = { win32: { chrome: 'Google/Chrome', 'chrome-beta': 'Google/Chrome Beta', 'chrome-dev': 'Google/Chrome Dev', 'chrome-canary': 'Google/Chrome SxS', edge: 'Microsoft/Edge', 'edge-beta': 'Microsoft/Edge Beta', 'edge-dev': 'Microsoft/Edge Dev', 'edge-canary': 'Microsoft/Edge SxS', chromium: 'Chromium', brave: 'BraveSoftware/Brave-Browser', vivaldi: 'Vivaldi', }, darwin: { chrome: 'Google/Chrome', 'chrome-beta': 'Google/Chrome Beta', 'chrome-dev': 'Google/Chrome Dev', 'chrome-canary': 'Google/Chrome Canary', edge: 'Microsoft Edge', 'edge-beta': 'Microsoft Edge Beta', 'edge-dev': 'Microsoft Edge Dev', 'edge-canary': 'Microsoft Edge Canary', chromium: 'Chromium', brave: 'BraveSoftware/Brave-Browser', vivaldi: 'Vivaldi', }, linux: { chrome: 'google-chrome', 'chrome-beta': 'google-chrome-beta', 'chrome-dev': 'google-chrome-unstable', edge: 'microsoft-edge', 'edge-beta': 'microsoft-edge-beta', 'edge-dev': 'microsoft-edge-dev', chromium: 'chromium', brave: 'BraveSoftware/Brave-Browser', vivaldi: 'vivaldi', }, }; function userDataRoot() { if (process.platform === 'win32') return path.join(HOME, 'AppData', 'Local'); if (process.platform === 'darwin') return path.join(HOME, 'Library', 'Application Support'); return process.env.XDG_CONFIG_HOME || path.join(HOME, '.config'); } export function browserNames() { return Object.keys(CHANNELS[process.platform] || CHANNELS.linux); } export function browserDir(name) { const table = CHANNELS[process.platform] || CHANNELS.linux; const rel = table[name]; if (!rel) return null; const dir = path.join(userDataRoot(), ...rel.split('/')); // Windows and macOS append "User Data"; Linux uses the directory itself. return process.platform === 'linux' ? dir : path.join(dir, 'User Data'); } // work -> main, work-2 -> main-2, matching the agent-browser profile pool. export function profileDir(session) { const suffix = session === 'work' ? '' : '-' + session.replace(/^work-?/, ''); return path.join(PROFILES, 'main' + suffix); } // Both lines matter. Line 1 is the port. Line 2 is the browser target path, // which is the only route the M144 server accepts. export function readPortFile(dir) { const file = path.join(dir, 'DevToolsActivePort'); if (!fs.existsSync(file)) return null; const [port, browserPath] = fs.readFileSync(file, 'utf8').split('\n').map(s => s.trim()); return { port, browserPath: browserPath || null, file }; } // Resolve to { port, browserPath }. browserPath may be null on a classic // endpoint, where HTTP discovery still works. export function resolveEndpoint({ session, cdp, browser, userDataDir } = {}) { const explicit = cdp || process.env.AGENT_HANDS_CDP; if (explicit) { const m = String(explicit).match(/^wss?:\/\/[^/]+(\/devtools\/browser\/.+)$/); if (m) return { port: String(explicit).match(/:(\d+)/)[1], browserPath: m[1] }; if (/^\d+$/.test(explicit)) return recoverPath(explicit); throw new Error(`--cdp expects a port or a ws://host:port/devtools/browser/ url, got "${explicit}"`); } const dir = userDataDir || (browser ? browserDir(browser) : null); if (browser && !dir) { throw new Error( `unknown browser "${browser}" on ${process.platform}.\n` + ` known: ${browserNames().join(', ')}\n` + ` any other Chromium build works with --user-data-dir ` ); } if (dir) { const found = readPortFile(dir); if (!found) { const scheme = /edge/.test(browser || '') ? 'edge' : 'chrome'; throw Object.assign(new Error( `${browser || dir} is not exposing a debugging endpoint.\n` + ` looked for: ${path.join(dir, 'DevToolsActivePort')}\n` + ` fix: open ${scheme}://inspect/#remote-debugging in that browser and tick\n` + ` "Allow remote debugging for this browser instance"` ), { code: 'ENOSESSION' }); } return found; } const pooled = profileDir(session); const found = readPortFile(pooled); if (!found) { throw Object.assign(new Error( `session "${session}" is not running.\n` + ` looked for: ${path.join(pooled, 'DevToolsActivePort')}\n` + ` Start a browser with the right flags (prints the --cdp port to use next):\n` + ` agent-hands launch \n` + ` Or attach to a browser you already have open:\n` + ` agent-hands browsers\n` + (hasAgentBrowser() ? ` Or start the pooled session itself:\n` + ` agent-browser --session ${session} --profile "${pooled}" open --headed` : ` (--session names an agent-browser pool. agent-browser is not on PATH, so\n` + ` there is no pool here; launch and --browser need no extra install.)`) ), { code: 'ENOSESSION' }); } return found; } // A bare port gives no uuid. Classic endpoints do not need one. M144 endpoints // do, so look through known user data directories for a file naming that port. function recoverPath(port) { const external = browserNames().map(browserDir).filter(Boolean); for (const dir of [PROFILES, ...external]) { for (const d of candidateDirs(dir)) { const found = readPortFile(d); if (found && found.port === String(port)) return found; } } return { port: String(port), browserPath: null }; } function candidateDirs(root) { if (!fs.existsSync(root)) return []; const self = readPortFile(root) ? [root] : []; const kids = fs.readdirSync(root, { withFileTypes: true }) .filter(e => e.isDirectory()) .map(e => path.join(root, e.name)); return [...self, ...kids]; } // Kept for callers that still pass a session name only. export function devtoolsPort(session) { return resolveEndpoint({ session }).port; } import { recall as recallTab, remember as rememberTab } from './tab.mjs'; export class CDP { constructor(ws) { this.ws = ws; this.id = 0; this.pending = new Map(); this.sessionId = null; } // Classic HTTP discovery stays authoritative. agent-browser sessions also // write line 2, so keying off its presence would silently move every // existing session onto the flat-attach path. Probe first, fall back only // when /json/list is genuinely absent, which is the M144 case. static async connect(sessionOrOpts) { const opts = typeof sessionOrOpts === 'string' ? { session: sessionOrOpts } : sessionOrOpts; const { port, browserPath } = resolveEndpoint(opts); const external = Boolean(opts.cdp || opts.browser || opts.userDataDir); const key = storeKey(opts); // The chosen tab is written down so the next command returns to it instead // of re-picking whatever the user is looking at by then. See tab.mjs. const tag = cdp => { Object.assign(cdp, { key, external, port }); if (cdp.targetId) rememberTab(key, { targetId: cdp.targetId, title: cdp.title, url: cdp.url }); return cdp; }; const targets = await listTargets(port); if (targets) return tag(await CDP.attachPerPage(targets, { ...opts, key })); if (!browserPath) { throw new Error(`no CDP endpoint on port ${port}. The browser may have exited.`); } // A dead browser leaves its DevToolsActivePort behind, and that file looks // exactly like a live M144 endpoint: both serve no /json/list. Without this // check the connect walks into the daemon and reports "relay failed to // start", which sends the reader hunting for a relay bug that is not there. if (!(await portAlive(port))) { const { file } = readPortFile(profileDir(opts.session ?? 'work')) ?? {}; throw Object.assign(new Error( `nothing is listening on port ${port} — the browser it belonged to has exited.\n` + (opts.browser || opts.userDataDir || opts.cdp ? ` Reopen chrome://inspect#remote-debugging and read the current port.` : ` session "${opts.session}" is not running. Its DevToolsActivePort is stale.\n` + (file ? ` delete: ${file}\n` : '') + ` start it: agent-browser --session ${opts.session} --profile "${profileDir(opts.session)}" open --headed`) ), { code: 'ENOSESSION' }); } return tag(await CDP.attachFlat(port, browserPath, { ...opts, key })); } // Pre-existing path. One socket per page, no sessionId. static async attachPerPage(targets, { tab, key } = {}) { const page = pickPage(targets, tab, key); const cdp = await CDP.open(page.webSocketDebuggerUrl); // Anything that throws from here on must close the socket first. The caller // never received `cdp`, so nobody else can, and an open handle keeps the // event loop alive: the CLI prints its error and then hangs forever. try { cdp.url = page.url; cdp.title = page.title; cdp.targetId = page.id; cdp.tabWhy = page.why; await enableFocusEmulation(cdp); await clearAutomationHint(cdp); return cdp; } catch (e) { cdp.close(); throw e; } } // M144 path. One browser socket, targets over CDP, flat session. // // The socket is opened by a daemon, not here. M144 prompts the user to // authorize every new CDP connection, so a per-invocation socket would ask // on every command. One daemon means one prompt per browser run. static async attachFlat(port, browserPath, opts = {}) { const { tab, activate = true, key, page: wantPage = true } = opts; const wsUrl = `ws://127.0.0.1:${port}${browserPath}`; // Always the daemon. There is deliberately no un-shared variant: a socket // that can authorise itself is a second door into a browser holding the // user's live session, and the daemon is the only audited one. const cdp = await DaemonCDP.open(wsUrl); // Browser-level verbs (tabs) never touch a page. Picking one would probe // every tab and could wake a frozen one, for nothing. if (!wantPage) return cdp; // Same reason as attachPerPage: a throw here (no tab matched, a frozen tab, // a dead target) leaks the pipe and the process never exits. `--tab typo` // used to print its error and hang until the caller killed it. try { const { targetInfos } = await cdp.send('Target.getTargets'); const page = await choosePage(cdp, targetInfos, { tab, activate, key }); cdp.restoreTo = page.restoreTo; cdp.sessionId = page.sessionId; cdp.targetId = page.targetId; // refs bind to a tab, see snapshot.mjs cdp.url = page.url; cdp.title = page.title; cdp.tabWhy = page.why; cdp.tabMatches = page.matches; // The first setup call doubles as a liveness check. Edge 154 freezes a // tab again within seconds of it going to the background, so a tab that // answered the probe as hidden can be frozen by now. // A missed 2s deadline alone proves nothing (slow is not frozen), so the // full QUIET_MS check decides before anything is brought to the front. if (!(await enableFocusEmulation(cdp)) && activate && !cdp.restoreTo && await tabState(cdp, page.sessionId) === 'frozen') { const back = await visibleInWindowOf(cdp, page.all ? await page.all : [], page.targetId); if (!(await wake(cdp, page))) { if (back) await cdp.send('Target.activateTarget', { targetId: back }); throw new Error(`"${(page.title || page.url).slice(0, 48)}" froze and did not wake when activated.${WAKE_HINT}`); } cdp.restoreTo = back; cdp.tabWhy = `${page.why}, woken`; await enableFocusEmulation(cdp); } await clearAutomationHint(cdp); return cdp; } catch (e) { cdp.close(); throw e; } } // No approval here, by design. This opener serves pooled per-page sockets, // which never prompt. Authorising a browser is the daemon's job alone, so // approve.mjs has exactly one importer and "can this codebase authorise a // browser?" stays a one-line grep with one answer. static async open(wsUrl) { const ws = new WebSocket(wsUrl); await new Promise((ok, bad) => { ws.addEventListener('open', ok, { once: true }); ws.addEventListener('error', () => bad(new Error('CDP socket refused')), { once: true }); }); const cdp = new CDP(ws); ws.addEventListener('message', ev => { const msg = JSON.parse(ev.data); const p = cdp.pending.get(msg.id); if (!p) return; cdp.pending.delete(msg.id); msg.error ? p.bad(new Error(msg.error.message)) : p.ok(msg.result); }); return cdp; } // sessionId is injected here so gestures.mjs needs no change. Browser-domain // calls must not carry a page sessionId. envelope(method, params, id, session = this.sessionId) { const browserDomain = method.startsWith('Target.') || method.startsWith('Browser.'); const sid = browserDomain ? null : session; return { ...(id != null ? { id } : {}), method, params, ...(sid ? { sessionId: sid } : {}) }; } // session overrides this.sessionId for one call, so several tabs can be // probed without mutating shared state. send(method, params = {}, session) { const id = ++this.id; this.ws.send(JSON.stringify(this.envelope(method, params, id, session ?? this.sessionId))); return new Promise((ok, bad) => this.pending.set(id, { ok, bad })); } // Input.* and in-page scroll writes: send, do not await. See header note. fire(method, params = {}, session) { this.ws.send(JSON.stringify(this.envelope(method, params, ++this.id, session ?? this.sessionId))); } async evaluate(expression) { const { result } = await this.send('Runtime.evaluate', { expression, returnByValue: true }); return result.value; } // Round-trip a cheap call so queued input flushes before the socket closes. // Bounded: a tab the browser froze again never answers, and an unbounded // drain held the CLI open for 41s after the work was done. // // Then hand the foreground back. A tab woken from a freeze stays in front // for the whole command, because Edge 154 freezes it again within 3s of // going to the background. Every call after an early hand-back hung. async drain() { // handoff closes a launched browser's page socket early. A closed socket // drops sends silently, so the flush would only burn its 2 s deadline. if (this.ws && this.ws.readyState > 1) return; await withDeadline(this.evaluate('0').catch(() => {}), 2000); if (!this.restoreTo) return; const targetId = this.restoreTo; this.restoreTo = null; await withDeadline(this.send('Target.activateTarget', { targetId }, null).catch(() => {}), 2000); } close() { this.ws.close(); } } // Same surface as CDP, but the browser socket lives in the daemon. Every // method gestures.mjs touches — send, fire, evaluate, drain, close — behaves // identically, so callers cannot tell the difference. export class DaemonCDP extends CDP { constructor(sock) { super(null); this.sock = sock; } static async open(wsUrl) { const pipe = pipeName(wsUrl); if (!(await probe(pipe))) await DaemonCDP.spawnDaemon(wsUrl, pipe); const sock = await new Promise((ok, bad) => { const s = net.connect(pipe); s.once('connect', () => ok(s)); s.once('error', e => bad(new Error(`daemon unreachable on ${pipe}: ${e.message}`))); }); const cdp = new DaemonCDP(sock); sock.setEncoding('utf8'); // see daemon.mjs: chunk-split multi-byte chars // Introduce ourselves before any CDP traffic. Verb and flag names only — // never argument values, which carry passwords. See audit.mjs. sock.write(JSON.stringify({ __hello: { pid: process.pid, cmd: safeCommand(process.argv[2] ?? '?', process.argv.slice(3)), } }) + '\n'); let buf = ''; sock.on('data', chunk => { buf += chunk; let i; while ((i = buf.indexOf('\n')) >= 0) { const line = buf.slice(0, i); buf = buf.slice(i + 1); if (!line) continue; let msg; try { msg = JSON.parse(line); } catch { continue; } const p = cdp.pending.get(msg.id); if (!p) continue; cdp.pending.delete(msg.id); msg.error ? p.bad(new Error(msg.error.message)) : p.ok(msg.result); } }); return cdp; } // Waits for the pipe rather than sleeping a fixed time: the user may take a // moment to click Allow. A dead relay must say why — polling a pipe that will // never appear, in silence, is the worst possible failure here. static spawnDaemon(wsUrl, pipe) { const here = path.dirname(fileURLToPath(import.meta.url)); const child = spawn(process.execPath, [path.join(here, 'daemon.mjs'), wsUrl], { detached: true, stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true, }); let stderr = ''; child.stderr.on('data', d => { stderr += d; }); child.unref(); return new Promise((ok, bad) => { let dead = false; child.on('exit', code => { if (code !== 0) dead = true; }); // The stderr pipe holds the parent's event loop open. unref() covers the // child handle, not this stream, so drop it once we have an answer. const settle = fn => v => { child.stderr.destroy(); fn(v); }; ok = settle(ok); bad = settle(bad); const deadline = Date.now() + 60_000; (async function poll() { if (await probe(pipe)) return ok(); if (dead) { const why = stderr.trim().split('\n').pop() || `exited without a message`; // A refusal here is almost never a relay bug. A browser that was // closed can leave a background process holding the port and // answering HTTP, so the endpoint looks alive right up until the // websocket, which it rejects in milliseconds. Say that, because the // message used to send readers hunting through the daemon. const refused = /refused/i.test(why); return bad(Object.assign(new Error( `relay failed to start: ${why}` + (refused ? `\n The debugging port answers, but the browser rejected the socket.` + `\n Usually it was closed and left the port behind, or the endpoint uuid` + `\n rotated when remote debugging was toggled.` + `\n Check what is really reachable: agent-hands browsers` + `\n Then re-enable debugging in the browser you want and retry.` : '') ), { code: refused ? 'ENOSESSION' : 'EFAIL' })); } if (Date.now() > deadline) { return bad(new Error( 'relay did not start within 60s.\n' + ' The browser asks you to approve each new debugging connection.\n' + ' If no prompt appeared, the endpoint may be stale — reopen\n' + ' chrome://inspect#remote-debugging and read the current port.' )); } setTimeout(poll, 250); })(); }); } #write(obj) { this.sock.write(JSON.stringify(obj) + '\n'); } send(method, params = {}, session) { const id = ++this.id; this.#write(this.envelope(method, params, id, session ?? this.sessionId)); return new Promise((ok, bad) => this.pending.set(id, { ok, bad })); } // No id: the daemon relays without tracking a reply. See CDP.fire. fire(method, params = {}, session) { this.#write(this.envelope(method, params, null, session ?? this.sessionId)); } // Closing a client must not close the shared browser socket. Tear the pipe // down synchronously: an end() still in flight when the process exits trips // a libuv assertion on Windows (UV_HANDLE_CLOSING in async.c). close() { for (const p of this.pending.values()) p.bad(new Error('connection closed')); this.pending.clear(); this.sock.removeAllListeners(); this.sock.destroy(); this.sock.unref?.(); } } // Without OS focus Chrome refuses DOM focus to clicked fields, so keystrokes // go nowhere. Emulate focus rather than raising the window, which would steal // focus from whatever the user is doing. // // A backgrounded tab can accept this command and never acknowledge it. The // promise then neither resolves nor rejects, so .catch() cannot rescue it and // the caller hangs forever. The call is best-effort, so bound it and continue. // Promise.race leaves the loser pending. A bare setTimeout keeps Node's event // loop alive until it fires, so a 2s guard that was won in 5ms still cost the // process a full 2s before it could exit. Measured: every browser-touching // command paid ~2s of dead wait at teardown because of this. Clear the timer. function withDeadline(work, ms) { let timer; return Promise.race([ work, new Promise(resolve => { timer = setTimeout(resolve, ms); }), ]).finally(() => clearTimeout(timer)); } // Resolves true when the tab answered (an error is an answer), undefined when // it did not answer within the deadline. async function enableFocusEmulation(cdp) { return withDeadline( cdp.send('Emulation.setFocusEmulationEnabled', { enabled: true }).then(() => true, () => true), 2000); } // Attaching over CDP sets navigator.webdriver = true, and a page reads it in one // line. Three things were measured on Chrome 151 before settling on this: // // Emulation.setAutomationOverride {enabled:false} returns {} — no error, the // method exists — and does NOT clear the flag. Not after a navigation inside // the same session either. It looks like a fix and is not one. // // The getter must return BOOLEAN FALSE, not undefined. Real Chrome reports // false. Deleting the property is its own tell: rebrowser's detector answers // "This property shouldn't be undefined. You might have it deleted manually." // and stays red. Shadowing it with undefined trades one red flag for another. // // Page.enable is required. addScriptToEvaluateOnNewDocument returns an // identifier without it and the script never runs. // // The accessor goes on Navigator.prototype, where the native one lives. An own // property on the `navigator` instance is its own tell: real Chrome answers // undefined to Object.getOwnPropertyDescriptor(navigator, 'webdriver'). // // Scope, stated honestly: // // Documents created while we are attached are covered, so this covers pages // opened through `agent-hands open`. The shim survives in that document after // we disconnect, because it was installed at document creation. A page the // user navigates to later, with nothing attached, is not covered. // // The script runs in the page's MAIN world, so it shares an execution context // with any anti-fraud script on the page. Fine for a one-line defineProperty. // Weigh it again before putting anything larger in here. // // A redefined getter is still detectable through Function.prototype.toString: // the native one reports "function get webdriver() { [native code] }" and this // one reports an arrow function. rebrowser does not probe that. CreepJS does. // So green here means green on this detector. If a real target ever rejects // us, look here first. // // Page.enable is a different domain from Runtime.enable and does not trip the // runtimeEnableLeak detector. const WEBDRIVER_SHIM = "Object.defineProperty(Navigator.prototype,'webdriver'," + "{get:()=>false,configurable:true,enumerable:true});"; async function clearAutomationHint(cdp) { await withDeadline((async () => { await cdp.send('Page.enable').catch(() => {}); await cdp.send('Page.addScriptToEvaluateOnNewDocument', { source: WEBDRIVER_SHIM }) .catch(() => {}); })(), 2000); } // Refs and cursor position belong to a BROWSER, not to --session. `session` // defaults to "work" even when --browser points somewhere else entirely, so // keying state on it made two different external browsers share one cursor // file, and sent `--ref` lookups to whatever the pool happened to be running. // Same input as pipeName(), so a pipe, a ref store and an audit line correlate. export function storeKey(opts = {}) { if (!opts.cdp && !opts.browser && !opts.userDataDir) return opts.session ?? 'work'; const { port, browserPath } = resolveEndpoint(opts); const h = crypto.createHash('sha1') .update(`ws://127.0.0.1:${port}${browserPath ?? ''}`).digest('hex').slice(0, 8); return `${opts.browser || (opts.userDataDir ? 'dir' : 'cdp')}-${h}`; } // Does anything hold this port open? A live M144 endpoint accepts TCP and // serves no /json/list; a dead browser's leftover port file does neither. export function portAlive(port, timeout = 1500) { return new Promise(resolve => { const s = net.connect({ port: Number(port), host: '127.0.0.1' }); const done = v => { s.destroy(); resolve(v); }; s.setTimeout(timeout, () => done(false)); s.once('connect', () => done(true)); s.once('error', () => done(false)); }); } // null means the endpoint serves no /json/list, not that there are no tabs. // A port that accepts TCP but never answers would hang an unbounded fetch. async function listTargets(port) { try { const r = await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(3000) }); if (!r.ok) return null; return await r.json(); } catch { return null; } } function pickPage(targets, tab, key) { const pages = targets.filter(t => t.type === 'page'); if (!tab && key) { const was = recallTab(key); const hit = was && pages.find(t => t.id === was.targetId); if (hit) return { ...hit, why: 'remembered' }; } // --tab used to be honoured only on the flat path, so on a classic endpoint // it was silently dropped and the command ran against whatever tab came // first. A flag that is quietly ignored is worse than one that errors. if (tab) { const q = String(tab).toLowerCase(); const hit = pages.find(t => `${t.title} ${t.url}`.toLowerCase().includes(q)); if (!hit) { throw Object.assign(new Error( `no tab matches "${tab}". Open tabs:\n` + pages.map(t => ` ${(t.title || '').slice(0, 48).padEnd(48)} ${t.url.slice(0, 60)}`).join('\n') ), { code: 'EUSAGE' }); } return { ...hit, why: 'match' }; } const page = pages.find(t => !/^(chrome|edge|devtools):/.test(t.url)) || pages[0]; if (!page) throw new Error('no page target found. Open a tab first.'); return { ...page, why: 'first' }; } const INTERNAL = /^(chrome|edge|devtools|about|brave|vivaldi):/; // Chrome's Memory Saver freezes tabs the user has not touched. A frozen tab // accepts page-session commands and never answers them, so anything awaiting a // reply hangs forever. A tab that is merely hidden answers normally, so the // probe has to distinguish the two rather than assume background means broken. // // SLOW IS NOT FROZEN. A busy app answers late: measured 3 Oct 2026 on Edge // 154, the user's VISIBLE WhatsApp Web tab took 3.9-4.9s to answer a first // evaluate, Play Console 5.6s. The old 2.5s limit called those tabs frozen, // "woke" them by switching the user's screen, and still failed. A frozen tab // never answers at all, so only a long silence means frozen. const QUIET_MS = 10_000; async function tabState(cdp, sessionId) { const FROZEN = Symbol('frozen'); const answer = await withDeadline( cdp.send('Runtime.evaluate', { expression: 'document.visibilityState', returnByValue: true }, sessionId) .catch(() => FROZEN), QUIET_MS); // withDeadline resolves undefined on timeout and clears its timer, so a // probe that lost the race does not hold the process open. if (!answer || answer === FROZEN) return 'frozen'; return answer.result.value; // 'visible' | 'hidden' } // Only Target.activateTarget thaws a frozen tab. Page.setWebLifecycleState // returns without thawing it and Emulation.setFocusEmulationEnabled hangs. // Activating steals the user's foreground. It is put back in drain(), after the // command, never straight after the wake: Edge 154 froze the woken tab again // within 3s of hiding it, and every call after that hung. async function choosePage(cdp, targets, { tab, activate, key }) { const pages = targets.filter(t => t.type === 'page'); if (!pages.length) throw new Error('no page target found. Open a tab first.'); // Memory beats visibility. The visible tab is whatever the user is looking // at, which changes under the agent between two commands; the remembered // tab is the one this CLI drove last, which is what the agent means. const was = !tab && key ? recallTab(key) : null; const remembered = was && pages.find(p => p.targetId === was.targetId); let why = tab ? 'match' : remembered ? 'remembered' : 'visible'; const wanted = tab ? pages.filter(p => `${p.title} ${p.url}`.toLowerCase().includes(tab.toLowerCase())) : remembered ? [remembered] : pages.filter(p => !INTERNAL.test(p.url)); if (tab && !wanted.length) { throw new Error( `no tab matches "${tab}". Open tabs:\n` + pages.map(p => ` ${(p.title || '(untitled)').slice(0, 48)} ${p.url.slice(0, 60)}`).join('\n') ); } const candidates = wanted.length ? wanted : pages; const matches = tab ? wanted.length : 0; const { settled, all } = probeTabs(cdp, pages, candidates); const probed = await settled; const byId = new Map(probed.map(p => [p.targetId, p])); const wantedProbed = candidates.map(c => byId.get(c.targetId)); const live = wantedProbed.find(p => p.state === 'visible') || wantedProbed.find(p => p.state === 'hidden'); if (live) { if (why === 'visible' && live.state === 'hidden') why = 'hidden'; detachOthers(cdp, all, live.sessionId); const visibleId = probed.find(p => p.state === 'visible')?.targetId ?? null; return { ...live, visibleId, matches, why, all }; } const target = wantedProbed[0]; const name = (target.title || target.url).slice(0, 48); if (!activate) { throw new Error( `"${name}" is frozen by the browser's memory saver.\n` + ` Waking it means bringing it to the front for a moment.\n` + ` Drop --no-activate to allow that, or switch to the tab yourself.` ); } // Waking needs to know where focus goes back, so wait for every probe here. // They all started together, so this costs at most the same QUIET_MS. const everyone = await all; const restoreTo = await visibleInWindowOf(cdp, everyone, target.targetId); const visibleId = restoreTo; detachOthers(cdp, all, target.sessionId); if (!(await wake(cdp, target))) { if (restoreTo) await cdp.send('Target.activateTarget', { targetId: restoreTo }); throw new Error(`"${name}" stayed frozen after being activated.${WAKE_HINT}`); } // The caller hands the foreground back in drain(), after the command. return { ...target, restoreTo, visibleId, matches, why: `${why}, woken` }; } // The tab to hand focus back to: the one the user sees in the SAME window as // the tab being woken. Activating a tab only changes its own window, and with // several windows open, "the first visible tab" can sit in another one. // Restoring that would raise a window the user was not using. async function visibleInWindowOf(cdp, probed, targetId) { const windowOf = async id => { try { return (await cdp.send('Browser.getWindowForTarget', { targetId: id }, null)).windowId; } catch { return null; } }; const home = await windowOf(targetId); if (home == null) return null; for (const p of probed) { if (p.state !== 'visible' || p.targetId === targetId) continue; if (await windowOf(p.targetId) === home) return p.targetId; } return null; } // Every probe attached a session to a tab, and the shared browser socket keeps // them until the browser exits: one per tab per command, piling up. An // attached session is also what sets navigator.webdriver on that tab. Drop // every session except the one this command drives. function detachOthers(cdp, all, keep) { all.then(rs => { for (const r of rs) { if (r.sessionId && r.sessionId !== keep) { cdp.send('Target.detachFromTarget', { sessionId: r.sessionId }, null).catch(() => {}); } } }); } // The lasting fix is the browser's own exception list. CDP cannot keep a // background tab awake: Page.setWebLifecycleState was tested and does not. const WAKE_HINT = '\n Retry once, or pick another tab with --tab .' + '\n agent-hands tabs lists them without waking any.' + '\n If this site keeps freezing, the user MAY add it to the keep-awake list.' + '\n That is their choice; do not ask on a first failure:' + '\n Edge: edge://settings/system/managePerformance -> "Never put these sites to sleep"' + '\n Chrome: chrome://settings/performance -> "Always keep these sites active"'; // Bring a tab to the front and wait until it answers. Thawing is not instant: // a heavy Vercel tab took 2.6s on Edge 154. async function wake(cdp, target) { await cdp.send('Target.activateTarget', { targetId: target.targetId }); return await tabState(cdp, target.sessionId) !== 'frozen'; } // Attach to every page and read its visibility, all at once. `settled` // resolves as soon as the choice is known, so a slow or frozen tab nobody // asked for costs nothing: a candidate answered 'visible', or every candidate // answered. Several tabs can be visible, one per window. Pages still pending // then are returned with state 'unknown'. `all` resolves when every probe is // done, for the callers that need the full picture. function probeTabs(cdp, pages, candidates) { const wanted = new Set(candidates.map(c => c.targetId)); const results = new Map(); const snapshot = () => pages.map(p => results.get(p.targetId) ?? { ...p, state: 'unknown' }); let settle; const settled = new Promise(r => { settle = r; }); const isSettled = () => { const done = [...results.values()].filter(r => wanted.has(r.targetId)); return done.some(r => r.state === 'visible') || done.length === wanted.size; }; const all = Promise.all(pages.map(async p => { let r; try { const { sessionId } = await cdp.send('Target.attachToTarget', { targetId: p.targetId, flatten: true }); r = { ...p, sessionId, state: await tabState(cdp, sessionId) }; } catch { r = { ...p, state: 'frozen' }; } results.set(p.targetId, r); if (isSettled()) settle(snapshot()); return r; })); return { settled, all }; } // A new background tab, so the page the user is reading stays where it is. // Flat path only: on a classic endpoint every page is its own socket and // switching would mean reconnecting, which the caller does not expect. export async function newTab(cdp, url) { if (!cdp.sessionId) { throw Object.assign(new Error( 'a new tab needs the shared-socket endpoint (a browser you attached to).\n' + ' On this browser use: agent-hands open --here'), { code: 'EUSAGE' }); } const { targetId } = await cdp.send('Target.createTarget', { url, background: true }, null); const { sessionId } = await cdp.send('Target.attachToTarget', { targetId, flatten: true }, null); cdp.sessionId = sessionId; cdp.targetId = targetId; cdp.url = url; cdp.title = ''; cdp.tabWhy = 'new'; await enableFocusEmulation(cdp); await clearAutomationHint(cdp); rememberTab(cdp.key, { targetId, title: '', url }); return targetId; } // Every page tab, with the one commands currently go to marked. export async function listTabs(cdp) { let pages; if (cdp instanceof DaemonCDP) { const { targetInfos } = await cdp.send('Target.getTargets', {}, null); pages = targetInfos.filter(t => t.type === 'page').map(t => ({ id: t.targetId, title: t.title, url: t.url })); } else { const all = (await listTargets(cdp.port)) ?? []; pages = all.filter(t => t.type === 'page').map(t => ({ id: t.id, title: t.title, url: t.url })); } // Connected without a page, the tab commands go to is the remembered one. const current = cdp.targetId ?? recallTab(cdp.key)?.targetId; return pages.map(p => ({ ...p, current: p.id === current })); } // Ground truth about the running browser. Browser.getVersion works on both // endpoint styles; /json/version does not exist on M144. export async function browserInfo(portOrCdp) { if (portOrCdp instanceof CDP) { try { const v = await portOrCdp.send('Browser.getVersion'); return { browser: v.product, headless: /Headless/i.test(v.product || v.userAgent || '') }; } catch { return { browser: null, headless: null }; } } try { const v = await (await fetch(`http://127.0.0.1:${portOrCdp}/json/version`)).json(); return { browser: v.Browser, headless: /Headless/i.test(v.Browser || '') || /Headless/i.test(v['User-Agent'] || ''), }; } catch { return { browser: null, headless: null }; } }