opera-devtools-mcp 0.6.1 → 0.8.0

package/build/src/opera/browserActivity.js

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * Who is using the shared browser at this moment.
+ *
+ * One daemon serves every terminal through one MCP server and one browser
+ * (`../browser.ts` holds a module-level singleton), so invocations that know
+ * nothing about each other overlap freely: an Opera AI action streams for
+ * minutes while another terminal's `take_snapshot` arrives, and a second
+ * `opera_do` joins the first. That is fine for reading the page and fatal for
+ * *replacing the browser*, which closes every page in it — including the pages
+ * of whatever is still running.
+ *
+ * `opera/browserFlags.ts` is the one thing that ever replaces the browser, and
+ * it asks here first. A count per tool name rather than a boolean because the
+ * refusal names the tools holding the browser, and because two invocations of
+ * the same tool are two claims rather than one.
+ *
+ * `ToolHandler` pairs `noteToolStarted` with `noteToolFinished` around every
+ * invocation, the second from the same `finally` that releases the tool mutex —
+ * so an invocation that fails is not left counted, and neither is one that
+ * `beforeInvoke` itself refused (`opera/toolHandlerHooks.ts`).
+ */
+const inFlight = new Map();
+/** Claim the browser for the invocation of `toolName` that is starting. */
+export function noteToolStarted(toolName) {
+    inFlight.set(toolName, (inFlight.get(toolName) ?? 0) + 1);
+}
+/** Release one claim on the browser; unknown names are ignored. */
+export function noteToolFinished(toolName) {
+    const count = inFlight.get(toolName);
+    if (count === undefined) {
+        return;
+    }
+    if (count > 1) {
+        inFlight.set(toolName, count - 1);
+        return;
+    }
+    inFlight.delete(toolName);
+}
+/**
+ * The tools using the browser besides the invocation of `self` asking, split by
+ * name so a refusal can name them, sorted so its wording is stable.
+ */
+export function otherBrowserUsers(self) {
+    const names = new Set();
+    for (const [name, count] of inFlight) {
+        if (name === self ? count > 1 : count > 0) {
+            names.add(name);
+        }
+    }
+    return [...names].sort();
+}
+/** Test seam: forget every in-flight invocation. */
+export function resetBrowserActivity() {
+    inFlight.clear();
+}
+//# sourceMappingURL=browserActivity.js.map

package/build/src/opera/browserCleanup.js

@@ -0,0 +1,123 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * Browser process-tree teardown, owned by Opera.
+ *
+ * Chrome calls `setsid()` while it initializes, so the browser is a process
+ * group leader and its helpers (GPU, renderer, utility) join *its* group rather
+ * than sitting below it in the process tree. That is why a helper survives
+ * SIGKILL to the main process: it is a sibling, not a child, so killing the
+ * parent orphans it instead of ending it.
+ *
+ * Killing the group is therefore the only teardown that reaches the helpers. A
+ * descendant walk from the browser pid cannot: by the time `disconnected`
+ * fires the pid is gone, the helpers are re-parented to init, and the walk
+ * returns nothing.
+ *
+ * On Linux the group id persists as long as any member is alive, even after the
+ * leader exits, so `kill(-pgid)` still names the whole group at that point.
+ *
+ * `watchBrowserForOrphans` is the seam `src/browser.ts` calls: it owns the pid
+ * capture and the `disconnected` listener, so the upstream file gets one line
+ * after `launch()` rather than a handler body.
+ */
+import process from 'node:process';
+/**
+ * SIGKILL every process in the browser's process group.
+ *
+ * Synchronous by design: `process.kill` is a syscall, and this runs from the
+ * `disconnected` handler, where the SIGKILL has to reach the group before the
+ * event loop yields to whatever teardown is already in flight.
+ *
+ * Takes the group id rather than the `Browser`: `browser.process()` is not
+ * reliable once `disconnected` has fired — the main process is gone, and a pid
+ * read at that point could already name an unrelated process that the kernel
+ * reused. The caller captures the pid at launch and holds it; the group outlives
+ * its leader, so that value still addresses every helper.
+ *
+ * No-op on Windows, which has no POSIX process groups: there the browser's
+ * helpers are its children and Puppeteer's own close path reaps them.
+ */
+export function killBrowserProcessGroup(pid) {
+    if (process.platform === 'win32' || !pid) {
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        // ESRCH — the group is already gone, which is what a graceful `close()`
+        // leaves behind, so the signal is a no-op either way. EPERM — the browser
+        // is not a group leader, which `setsid()` makes impossible for a browser
+        // Puppeteer launched.
+    }
+}
+/**
+ * Whether the teardown above must stay its hand — set while *we* close the
+ * browser.
+ *
+ * `disconnected` is not an abnormal-exit signal: Puppeteer's own `close()` ends
+ * with `disconnect()`, so a deliberate shutdown fires the same event a crash
+ * does. Killing the process group at that moment SIGKILLs a browser that is
+ * still flushing its profile — IndexedDB and LevelDB writes are done by its
+ * child storage utility, not by the browser process — and a store that loses
+ * those writes keeps records pointing at files that never landed. Blink reports
+ * the read of such a record as `NotReadableError: Data lost due to missing
+ * file. Affected record should be considered irrecoverable` (`indexeddb/`
+ * `idb_request_queue_item.cc`), and Opera AI's chat path then fails on every
+ * later run in that profile.
+ *
+ * So the group kill is armed for a browser that goes away without us closing
+ * it, and disarmed for the close we asked for.
+ *
+ * The flag lives in the watching handler's closure, not in module state: a
+ * handler for a browser we already closed can fire *after* the next launch has
+ * installed its own, and module state would then be read through the new cycle
+ * — an arm resets it to false, so the late handler for the deliberately closed
+ * browser sees "not ours" and SIGKILLs a group whose helpers may still be
+ * flushing that profile. One flag per armed handler means each browser's
+ * teardown answers only for its own close.
+ */
+let disarmActiveWatcher;
+/**
+ * Mark the teardown that follows as deliberate, so the `disconnected` it emits
+ * is not answered with a group kill. Called by both browser-closing paths in
+ * `src/browser.ts`, which are the only places that close a browser we launched.
+ */
+export function disarmBrowserOrphanCleanup() {
+    disarmActiveWatcher?.();
+}
+/**
+ * Arm the browser's teardown: when it disconnects without closing, kill the
+ * process group it left behind.
+ *
+ * The pid is read here, while the browser is alive, because by the time
+ * `disconnected` fires the main process is gone and a pid read then could
+ * already name a process the kernel reused. `.once` because Puppeteer emits
+ * `disconnected` on an abnormal exit and again on `close()`, and one group kill
+ * is the whole job.
+ *
+ * Called from `ensureBrowserLaunched` right after `launch()`, which is the one
+ * place in `src/browser.ts` that owns a launched browser. Each launch installs
+ * a fresh watcher with its own disarm flag, so a browser launched after a
+ * deliberate close is protected again — and the previous launch's watcher,
+ * which may fire afterwards, is still answered by its own flag.
+ */
+export function watchBrowserForOrphans(browser) {
+    const pgid = browser.process()?.pid;
+    let disarmed = false;
+    disarmActiveWatcher = () => {
+        disarmed = true;
+    };
+    browser.once('disconnected', () => {
+        if (disarmed) {
+            return;
+        }
+        killBrowserProcessGroup(pgid);
+    });
+}
+//# sourceMappingURL=browserCleanup.js.map

package/build/src/opera/browserErrors.js

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+function attachTarget(target) {
+    return target.browserURL ?? target.wsEndpoint ?? target.userDataDir;
+}
+/**
+ * The opening of {@link profileInUse}, exported because a second caller has to
+ * recognise the failure without matching the prose again: the CLI settles a
+ * conflict it finds this way (see `cliCommands.ts`), and the two spellings of
+ * "the profile is in use" must not drift apart.
+ */
+export const PROFILE_IN_USE_PREFIX = 'A browser is already running with the profile';
+/** A launch failed because a browser already holds the profile. */
+export function profileInUse(userDataDir) {
+    return (`${PROFILE_IN_USE_PREFIX} ${userDataDir}, so a second one cannot be launched on it. ` +
+        `Either drive that browser — start it with --remote-debugging-port=<port> (9222 is the usual one) and run with --browser-url=http://127.0.0.1:<port> ` +
+        `(or --autoConnect on Chrome 144+) — or launch on a separate profile with --isolated.`);
+}
+/** Whether a failure message is one {@link profileInUse} produced. */
+export function isProfileInUseMessage(message) {
+    return message.includes(PROFILE_IN_USE_PREFIX);
+}
+/**
+ * The opening of {@link attachFailed} and {@link noDevToolsEndpoint}, which
+ * both say the daemon was told to drive a browser that is not there.
+ */
+export const ATTACH_FAILED_PREFIX = 'Could not attach to the browser';
+/**
+ * The browser failure a tool reply describes, or undefined when it describes
+ * none.
+ *
+ * Both of these mean the daemon has no browser to drive — one because a launch
+ * was refused, the other because the browser it attached to is gone — and both
+ * leave it that way until something re-reads the environment, because a daemon
+ * fixes its browser at startup. `cliCommands.ts` settles them for that reason.
+ */
+export function classifyBrowserFailure(message) {
+    if (isProfileInUseMessage(message)) {
+        return 'profile-in-use';
+    }
+    if (message.includes(ATTACH_FAILED_PREFIX)) {
+        return 'unreachable';
+    }
+    return undefined;
+}
+/**
+ * An attach through a profile found no DevTools endpoint in it, i.e. the browser
+ * is running but was not started with remote debugging.
+ */
+export function noDevToolsEndpoint(userDataDir) {
+    return (`Could not attach to the browser running with the profile ${userDataDir}: no DevTools endpoint was found there. ` +
+        `Check that it is running and that remote debugging is enabled (chrome://inspect/#remote-debugging).`);
+}
+/** An attach failed outright: the browser is gone, or not debuggable. */
+export function attachFailed(target, autoConnect) {
+    const at = attachTarget(target);
+    const hint = autoConnect ? ' (chrome://inspect/#remote-debugging)' : '';
+    return (`Could not attach to the browser${at ? ` at ${at}` : ''}. ` +
+        `Check that it is running with remote debugging enabled${hint}. ` +
+        `An attached browser is not managed by this daemon, so it is not restarted for you — start it again and re-attach.`);
+}
+//# sourceMappingURL=browserErrors.js.map

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