opera-devtools-mcp 0.7.0 → 0.8.0

package/build/src/daemon/daemon.js

@@ -4,11 +4,17 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import fs, { constants, openSync, writeSync, closeSync } from 'node:fs';
+import fs, { constants, writeSync, closeSync } from 'node:fs';
 import { createServer } from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
+import { claimPidFile } from '../opera/daemonPidFile.js';
+import { installShutdownHandlers, recordShutdownReason, } from '../opera/daemonShutdown.js';
+import { dispatchSocketMessage, reportStartupFailure, } from '../opera/daemonSocket.js';
+import { attachLogForwarding } from '../opera/daemonStreaming.js';
+import { callDaemonTool } from '../opera/daemonToolCall.js';
+import { superviseMcpServer } from '../opera/mcpServerSupervisor.js';
 import { Client, PipeTransport, StdioClientTransport, } from '../third_party/index.js';
 import { logger, puppeteerLogger } from '../utils/logger.js';
 import { VERSION } from '../version.js';
@@ -54,16 +60,11 @@ catch (err) {
 }
 let fd = -1;
 try {
-    // Open the file with flags to:
-    // - O_WRONLY: Write-only
-    // - O_CREAT: Create if it doesn't exist
-    // - O_TRUNC: Truncate to zero length if it exists
-    // - O_NOFOLLOW: DO NOT follow symlinks.
-    // - 0o600: Permissions: read/write for owner, no permissions for others.
-    fd = openSync(pidFilePath, constants.O_WRONLY |
-        constants.O_CREAT |
-        constants.O_TRUNC |
-        constants.O_NOFOLLOW, 0o600);
+    // The claim is `O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW` — write only,
+    // create if absent, fail if another daemon owns it, never follow a symlink —
+    // at 0o600. See `opera/daemonPidFile.ts` for why it is not upstream's
+    // `O_TRUNC`.
+    fd = claimPidFile(sessionId);
     writeSync(fd, process.pid.toString());
 }
 catch (err) {
@@ -88,33 +89,54 @@ const mcpServerArgs = process.argv.slice(2);
 let mcpClient = null;
 let mcpTransport = null;
 let server = null;
+/** Set once `listen` succeeds, so a later failure knows it owns the socket. */
+let bound = false;
+/** Brings the MCP server back when its stdio child dies; see the module. */
+const mcpSupervisor = superviseMcpServer({
+    sessionId,
+    connect: setupMCPClient,
+    handles: () => ({ client: mcpClient, transport: mcpTransport }),
+    giveUp: () => cleanup(1),
+});
 async function setupMCPClient() {
     console.log('Setting up MCP client connection...');
     // Create stdio transport for chrome-devtools-mcp
-    mcpTransport = new StdioClientTransport({
+    const transport = new StdioClientTransport({
         command: process.execPath,
         args: [INDEX_SCRIPT_PATH, ...mcpServerArgs],
         env: process.env,
     });
+    mcpTransport = transport;
     mcpClient = new Client({
         name: DAEMON_CLIENT_NAME,
         version: VERSION,
     }, {
         capabilities: {},
     });
-    await mcpClient.connect(mcpTransport);
+    // Set onclose BEFORE connect: the SDK's Protocol.connect() captures the
+    // transport's existing onclose and wraps it. Setting it after connect
+    // overwrites that wrapper, so _onclose() never runs and pending callTool
+    // requests hang forever when the MCP server dies. The callback carries the
+    // transport it belongs to, so a respawn can tell a server it replaced from the
+    // one it is watching.
+    transport.onclose = () => mcpSupervisor.onTransportClosed(transport);
+    await mcpClient.connect(transport);
+    // Opera AI tools stream their output as `notifications/message` chunks; the
+    // socket protocol carries them to the CLI. See `opera/daemonStreaming.ts`.
+    attachLogForwarding(mcpClient);
     console.log('MCP client connected');
 }
-async function handleRequest(msg) {
+async function handleRequest(msg, streamToken) {
     try {
         if (msg.method === 'invoke_tool') {
             if (!mcpClient) {
                 throw new Error('MCP client not initialized');
             }
             const { tool, args } = msg;
-            const result = (await mcpClient.callTool({
-                name: tool,
-                arguments: args || {},
+            const result = (await callDaemonTool(mcpClient, {
+                tool,
+                args,
+                streamToken,
             }));
             return {
                 success: true,
@@ -126,7 +148,7 @@ async function handleRequest(msg) {
             await started;
             // Trigger cleanup asynchronously.
             setImmediate(() => {
-                void cleanup();
+                void cleanup(0, 'stopped by request');
             });
             return {
                 success: true,
@@ -177,7 +199,7 @@ async function startSocketServer() {
             const transport = new PipeTransport(socket, socket, puppeteerLogger);
             transport.onmessage = async (message) => {
                 logger?.('onmessage', message);
-                const response = await handleRequest(JSON.parse(message));
+                const response = await dispatchSocketMessage(message, transport, handleRequest);
                 transport.send(JSON.stringify(response));
                 socket.end();
             };
@@ -190,6 +212,7 @@ async function startSocketServer() {
             readableAll: false,
             writableAll: false,
         }, async () => {
+            bound = true;
             console.log(`Daemon server listening on ${socketPath}`);
             try {
                 // Setup MCP client
@@ -206,7 +229,14 @@ async function startSocketServer() {
         });
     });
 }
-async function cleanup(exitCode = 0) {
+async function cleanup(exitCode = 0, reason) {
+    // The reason is the diagnostic, so it goes first: `recordShutdownReason` is
+    // best-effort, and nothing else in this teardown should be able to cost us it.
+    recordShutdownReason(sessionId, reason);
+    // Then stop supervising. Closing the client below closes the transport, which
+    // would otherwise land in the respawn path and spawn a replacement server
+    // while this teardown is running.
+    mcpSupervisor.stop();
     console.log('Cleaning up daemon...');
     try {
         await mcpClient?.close();
@@ -239,28 +269,21 @@ async function cleanup(exitCode = 0) {
     }
     process.exit(exitCode);
 }
-// Handle shutdown signals
-process.on('SIGTERM', () => {
-    void cleanup();
-});
-process.on('SIGINT', () => {
-    void cleanup();
-});
-process.on('SIGHUP', () => {
-    void cleanup();
-});
-// Handle uncaught errors
-process.on('uncaughtException', error => {
-    logger?.('Uncaught exception:', error);
-    void cleanup(1);
-});
-process.on('unhandledRejection', error => {
-    logger?.('Unhandled rejection:', error);
-    void cleanup(1);
+// The shutdown wiring — three signals and the two uncaught-error handlers, each
+// naming itself in the reason the CLI reports — lives in
+// `opera/daemonShutdown.ts`. Every path that reaches it records why it left, so
+// "left no reason behind" means only what it says: a SIGKILL or the OOM killer.
+installShutdownHandlers({
+    onSignal: reason => cleanup(0, reason),
+    onException: reason => cleanup(1, reason),
 });
 // Start the server
 const started = startSocketServer().catch(error => {
     logger?.('Failed to start daemon server:', error);
-    void cleanup(1);
+    void reportStartupFailure(error, {
+        socketBound: bound,
+        sessionId,
+        teardown: reason => cleanup(1, reason),
+    });
 });
 //# sourceMappingURL=daemon.js.map

package/build/src/opera/branding.js

@@ -15,8 +15,10 @@
 export const PACKAGE_NAME = 'opera-devtools-mcp';
 /** MCP server binary / daemon app name, also used as `process.title`. */
 export const MCP_BIN_NAME = PACKAGE_NAME;
-/** CLI binary name, e.g. `opera-devtools start`. */
-export const CLI_BIN_NAME = 'opera-devtools';
+/** CLI binary name, e.g. `opera-browser-cli start`. The fork's sole CLI. */
+export const CLI_BIN_NAME = 'opera-browser-cli';
+/** Directory under `$HOME` holding the per-user config file (matches the CLI binary name). */
+export const STATE_DIR_NAME = '.opera-browser-cli';
 /** Human-readable product name used in log lines. */
 export const PRODUCT_NAME = 'Opera DevTools MCP Server';
 /** Public repository, referenced from help text and disclaimers. */

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