opera-devtools-mcp 0.7.0 → 0.8.1

package/build/src/opera/browserFlags.js

@@ -5,14 +5,22 @@
  * This file is an original work developed by Opera.
  */
 import { closeBrowserIfOpen, ensureBrowserLaunched, getCurrentBrowser, } from '../browser.js';
-import { buildLaunchOptions } from './browserLaunch.js';
 import { logger } from '../utils/logger.js';
+import { otherBrowserUsers } from './browserActivity.js';
+import { buildLaunchOptions } from './browserLaunch.js';
 /**
  * Opera's AI features refuse to run when the page reports itself as
  * automation-controlled, so the browser has to be launched with this flag for
  * them. It is deliberately NOT applied to every launch: it changes observable
  * page behaviour, which would silently alter results for ordinary DevTools
  * tools.
+ *
+ * The flags are therefore acquired the first time an Opera AI tool needs them
+ * and then kept for the life of that browser — see `ensureBrowserFlagsForTool`.
+ * A browser carrying them is never relaunched to take them away again: the
+ * daemon serves several terminals at once, and the tool that used to trigger
+ * that relaunch was an ordinary one (`take_snapshot` in another terminal), which
+ * closed the browser a running `opera_do` was streaming from.
  */
 export const OPERA_AUTOMATION_FLAGS = [
     '--disable-blink-features=AutomationControlled',
@@ -27,59 +35,197 @@ export function toolRequiresOperaFlags(toolName) {
     return TOOLS_REQUIRING_OPERA_FLAGS.has(toolName);
 }
 /**
- * Tracks whether the currently running browser was launched with
- * {@link OPERA_AUTOMATION_FLAGS}. Module-level rather than per-server because
- * the browser itself is a module-level singleton in `../browser.ts`.
+ * The browser this server launched with {@link OPERA_AUTOMATION_FLAGS}, held by
+ * identity rather than as a flag that outlives it: a browser that died and was
+ * relaunched by the next call carries none of them (`index.ts` launches without
+ * the Opera flags), and the tools that need them must not be told otherwise.
+ * Module-level rather than per-server because the browser itself is a
+ * module-level singleton in `../browser.ts`.
  */
-let browserHasOperaFlags = false;
-export function browserWasLaunchedWithOperaFlags() {
-    return browserHasOperaFlags;
-}
-/** Test seam: forget what we believe about the current browser. */
+let flagsBrowser;
+/** Test seam: forget which browser was launched with the Opera flags. */
 export function resetOperaFlagState() {
-    browserHasOperaFlags = false;
+    flagsBrowser = undefined;
 }
+/**
+ * One source of truth for "did we launch the browser, or attach to one that was
+ * already running". `index.ts` picks the branch with the same three options at
+ * invocation time, and the CLI reports the mode from the daemon's stored argv,
+ * so the rule must not be re-implemented per caller.
+ */
+const ATTACH_OPTIONS = ['browserUrl', 'wsEndpoint', 'autoConnect'];
 /**
  * True when this server launched the browser itself. When the user attached to
  * an existing browser we must never kill and relaunch it.
  */
-function isLaunchMode(serverArgs) {
-    return (!serverArgs.browserUrl && !serverArgs.wsEndpoint && !serverArgs.autoConnect);
+export function isLaunchMode(serverArgs) {
+    return !ATTACH_OPTIONS.some(option => Boolean(serverArgs[option]));
 }
 /**
- * Makes sure the running browser has (or lacks) the Opera automation flags to
- * match what `toolName` needs, relaunching it if not. No-op when we did not
- * launch the browser ourselves, or when the flags already match.
+ * One canonical spelling for a raw flag name. yargs expands `--browser-url` and
+ * `--browserUrl` to the same option, and the daemon stores the argv verbatim, so
+ * a read-back that does not normalize would call an attached session "launched".
  */
-export async function ensureBrowserFlagsForTool(toolName, serverArgs, logFile, control, 
-// Injected so tests do not need a real browser singleton.
-deps = { closeBrowserIfOpen, ensureBrowserLaunched }) {
-    if (!isLaunchMode(serverArgs)) {
-        return;
+function canonicalOptionName(name) {
+    return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+/**
+ * The flags of a stored argv in one pass: canonical name → value, `true` for a
+ * value-less flag. `--flag=value`, `--flag value`, `--no-flag` and
+ * `--flag=false` all arrive on a real command line, and all four have to read
+ * the same as `isLaunchMode` reads the parsed form.
+ */
+function readFlags(args) {
+    const flags = new Map();
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (!arg.startsWith('--')) {
+            continue;
+        }
+        const body = arg.slice(2);
+        const equals = body.indexOf('=');
+        if (equals !== -1) {
+            flags.set(canonicalOptionName(body.slice(0, equals)), body.slice(equals + 1));
+            continue;
+        }
+        if (body.startsWith('no-')) {
+            flags.set(canonicalOptionName(body.slice(3)), false);
+            continue;
+        }
+        const next = args[index + 1];
+        if (next !== undefined && !next.startsWith('-')) {
+            flags.set(canonicalOptionName(body), next);
+            index++;
+            continue;
+        }
+        flags.set(canonicalOptionName(body), true);
     }
-    const needsOperaFlags = toolRequiresOperaFlags(toolName);
-    const browserConnected = getCurrentBrowser()?.connected ?? false;
-    // A disconnected browser tells us nothing about the flags of the next one.
-    if (needsOperaFlags && browserHasOperaFlags && browserConnected) {
+    return flags;
+}
+/**
+ * How a serialized CLI argv (`opera-browser-cli status`) describes the browser
+ * it drives: `launched (owned by this daemon)` or `attached to <target>`.
+ *
+ * The daemon stores the MCP argv it was started with, so this needs no new
+ * channel between the two processes — and it is the same predicate the server
+ * itself applies, read back from the flags that decided it.
+ */
+export function describeBrowserMode(args) {
+    const flags = readFlags(args);
+    const attachFlag = ATTACH_OPTIONS.find(option => {
+        const value = flags.get(option);
+        // `--flag=false` and `--no-flag` are how yargs spells "not set", and
+        // `isLaunchMode` reads them the same way.
+        return value !== undefined && value !== false && value !== 'false';
+    });
+    if (!attachFlag) {
+        return 'launched (owned by this daemon)';
+    }
+    const value = flags.get(attachFlag);
+    return `attached to ${typeof value === 'string' && value ? value : 'an external browser'}`;
+}
+/**
+ * The profile a stored argv's launched browser was pointed at, if any.
+ *
+ * Read back for the same reason `describeBrowserMode` is: a daemon fixes its
+ * browser at startup, so its argv is the only record of which profile that
+ * browser holds. The CLI uses it to tell its own browser — which never
+ * advertises a debug port, because it is launched over a pipe — from the one a
+ * user opened, which is the difference between "nothing to do" and "ask".
+ */
+export function launchedUserDataDir(args) {
+    const value = readFlags(args).get('userDataDir');
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/**
+ * The `--browser-url` a stored argv carries, if it carries one.
+ *
+ * That is the form the CLI's own endpoint discovery sets (`browserTarget.ts`
+ * finds a live `DevToolsActivePort` and passes the URL on), which makes it the
+ * one attach target the CLI may re-derive when the browser behind it is gone: a
+ * `--wsEndpoint` or `--autoConnect` was typed by the user, and their browser is
+ * theirs to start again.
+ */
+export function storedBrowserUrl(args) {
+    const value = readFlags(args).get('browserUrl');
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/**
+ * How long a relaunch waits for the browser to fall idle before it gives up and
+ * reports why, and how often it looks. A mutable object so tests can drive the
+ * wait without waiting: faking timers is not workable here (sinon's fake clock
+ * replaces the globals `node:test` schedules subtests with).
+ */
+export const browserIdleWaitPolicy = {
+    timeoutMs: 10_000,
+    pollMs: 100,
+};
+function sleep(ms) {
+    const { promise, resolve } = Promise.withResolvers();
+    setTimeout(resolve, ms);
+    return promise;
+}
+const defaultFlagRelaunchDeps = {
+    closeBrowserIfOpen,
+    ensureBrowserLaunched,
+    getCurrentBrowser,
+    sleep,
+};
+/**
+ * Wait until nothing else is inside a tool invocation, or refuse.
+ *
+ * A relaunch closes every page in the browser, which is defensible only when
+ * nothing is using it: the daemon answers several terminals at once, so the
+ * alternative is destroying the pages of an invocation that is still running —
+ * the failure this whole module exists to stop.
+ */
+async function waitForBrowserIdle(toolName, sleep) {
+    const deadline = Date.now() + browserIdleWaitPolicy.timeoutMs;
+    for (;;) {
+        const users = otherBrowserUsers(toolName);
+        if (users.length === 0) {
+            return;
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`${toolName} needs the browser relaunched with Opera's automation flags, and it is in use by ${users.join(', ')} — relaunching it now would close that work. Timed out waiting for the browser to be free; retry when it is.`);
+        }
+        await sleep(browserIdleWaitPolicy.pollMs);
+    }
+}
+/**
+ * Make sure the running browser has the Opera automation flags `toolName` needs.
+ *
+ * One direction only, and that is the point. A browser this daemon launched
+ * *gains* the flags when an Opera AI tool first needs them and keeps them for the
+ * rest of its life; a tool that needs no flags is not this module's business at
+ * all. The reverse relaunch — taking the flags away again for an ordinary
+ * DevTools tool — was what closed the browser under a running `opera_do` when a
+ * second terminal ran `take_snapshot`, failing both streams with the AI
+ * dispatcher's "no target" error, and it is gone rather than made conditional:
+ * the flags are a property of the browser, not of the tool that happens to be
+ * running.
+ *
+ * The one relaunch that remains — the acquisition — waits for the browser to fall
+ * idle first, and reports why instead of closing anything if it does not.
+ */
+export async function ensureBrowserFlagsForTool(toolName, serverArgs, logFile, control, deps = defaultFlagRelaunchDeps) {
+    if (!isLaunchMode(serverArgs) || !toolRequiresOperaFlags(toolName)) {
         return;
     }
-    if (!needsOperaFlags && !(browserHasOperaFlags && browserConnected)) {
+    const current = deps.getCurrentBrowser();
+    if (current?.connected && current === flagsBrowser) {
         return;
     }
-    logger?.(`Relaunching browser ${needsOperaFlags ? 'with' : 'without'} Opera automation flags for ${toolName}`);
+    await waitForBrowserIdle(toolName, deps.sleep);
+    logger?.(`Relaunching browser with Opera's automation flags for ${toolName}`);
     control.resetContext();
-    browserHasOperaFlags = false;
+    flagsBrowser = undefined;
     await deps.closeBrowserIfOpen();
-    if (needsOperaFlags) {
-        // Launch options come from the shared `buildLaunchOptions` so the relaunch
-        // applies exactly the same flags (including blocklist/allowlist and proxy)
-        // as the normal launch in `index.ts`, plus the automation flags.
-        await deps.ensureBrowserLaunched(buildLaunchOptions(serverArgs, logFile, {
-            extraChromeArgs: OPERA_AUTOMATION_FLAGS,
-        }));
-        browserHasOperaFlags = true;
-    }
-    // Otherwise leave the browser closed: getContext() relaunches it without the
-    // Opera flags on the next call.
+    // Launch options come from the shared `buildLaunchOptions` so the relaunch
+    // applies exactly the same flags (including blocklist/allowlist and proxy)
+    // as the normal launch in `index.ts`, plus the automation flags.
+    flagsBrowser = await deps.ensureBrowserLaunched(buildLaunchOptions(serverArgs, logFile, {
+        extraChromeArgs: OPERA_AUTOMATION_FLAGS,
+    }));
 }
 //# sourceMappingURL=browserFlags.js.map