opera-devtools-mcp 0.7.0 → 0.8.1

package/build/src/opera/daemonLifecycle.js

@@ -0,0 +1,257 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * Daemon lifecycle supervision, owned by Opera.
+ *
+ * The upstream daemon is spawned `detached: true` and `unref()`ed, so the CLI
+ * is not its parent and nothing recovers the process tree when it goes away
+ * badly. Two holes follow from that, and this module closes both without
+ * touching the daemon's own supervision of its children:
+ *
+ * 1. **Liveness is pid-file-only.** `isDaemonRunning` reads the pid file, so a
+ *    daemon whose pid file was removed (or whose socket was unlinked by a
+ *    racing starter) is invisible: the next `start` forks a second daemon and
+ *    the first keeps running as an orphan holding the session's real socket.
+ *    `ensureCleanStart` probes the socket itself — the one signal that survives
+ *    a missing pid file — and stops any daemon it finds there.
+ *
+ * 2. **A dead daemon leaves its process group behind.** SIGKILL (what the OOM
+ *    killer sends) runs no handler, so the MCP server and the browser stay up
+ *    re-parented to init. `ensureCleanStart` kills the whole process group of a
+ *    dead pid, which is what reaps them: the daemon is a session leader
+ *    (`detached: true` calls `setsid()`), so every child it spawned shares its
+ *    group id — including group members whose leader has already exited.
+ *
+ * Nothing here deletes the pid or socket files. File creation belongs to the
+ * daemon's own `O_EXCL` claim (`daemon.ts`); a client that unlinked them would
+ * reopen the race this module exists to close.
+ */
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import process from 'node:process';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { getDaemonPid, getRuntimeHome, getSocketPath, IS_WINDOWS, } from '../daemon/utils.js';
+import { PipeTransport } from '../third_party/index.js';
+import { logger, puppeteerLogger } from '../utils/logger.js';
+/** How long a socket probe waits to connect before concluding nothing is there. */
+const SOCKET_CONNECT_TIMEOUT_MS = 1_000;
+/**
+ * How long it then waits for the reply, once something accepted the connection.
+ * Longer than the connect wait on purpose: a daemon that connected is alive, and
+ * a busy one — a long tool call, a GC pause, a stalled disk — answers late rather
+ * than never. Declaring it dead on a 1s reply window forks a second daemon whose
+ * `O_EXCL` claim then fails, which reaches the user as a spurious startup error.
+ */
+const SOCKET_REPLY_TIMEOUT_MS = 5_000;
+/** How long to wait for a daemon to exit after asking it to stop. */
+const STOP_WAIT_TIMEOUT_MS = 5_000;
+const STOP_WAIT_POLL_MS = 50;
+/** Where a dying daemon explains itself to the next CLI invocation. */
+const EXIT_REASON_FILE = 'daemon-error';
+/**
+ * `process.kill(pid, 0)` with the semantics the callers want: `EPERM` means the
+ * pid exists but belongs to another user, which still counts as alive.
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * Get rid of a daemon that is known to be dead or unresponsive. POSIX: SIGKILL
+ * its whole process group, which is what reaps the MCP server, the browser and
+ * Chrome's helpers along with it (the daemon is a session leader, and the group
+ * outlives its leader as long as one member is alive).
+ *
+ * `ESRCH` (the group is already gone) is the expected outcome once the daemon
+ * exited cleanly, so it is not logged as a failure.
+ */
+function killStaleDaemon(pid) {
+    if (IS_WINDOWS) {
+        // No process groups to signal, so the daemon itself is the only handle
+        // available here. What it spawned is not reachable from this call.
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            // already gone
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+        logger?.(`Killed the process group of daemon ${pid}`);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ESRCH') {
+            logger?.(`Could not kill the process group of daemon ${pid}:`, error);
+        }
+    }
+}
+async function waitForProcessExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid)) {
+            return true;
+        }
+        await sleep(STOP_WAIT_POLL_MS);
+    }
+    return !isProcessAlive(pid);
+}
+/** The pid out of a raw `status` reply, or null if the reply is not one. */
+function readPidFromStatus(rawReply) {
+    try {
+        const response = JSON.parse(rawReply);
+        if (!response.success || typeof response.result !== 'string') {
+            return null;
+        }
+        const status = JSON.parse(response.result);
+        return typeof status.pid === 'number' ? status.pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Open the session's socket and send one framed command, resolving with the
+ * daemon's raw reply. `null` means the caller should act as if the session is
+ * empty: the socket file is missing, nobody accepts the connection, or the
+ * connection broke before a reply arrived.
+ *
+ * A connection that is accepted and then goes quiet is logged separately. It
+ * means a daemon exists and is too busy (or too wedged) to answer, which is a
+ * different thing to debug than no daemon at all — but the same thing to do
+ * about, because nothing here can stop a daemon that will not talk.
+ *
+ * This bypasses `sendCommand`, whose pid-file guard is the very check that
+ * cannot see the daemon we are looking for.
+ */
+async function probeSocket(sessionId, command) {
+    const socketPath = getSocketPath(sessionId);
+    const { promise, resolve } = Promise.withResolvers();
+    const socket = net.createConnection({ path: socketPath });
+    let settled = false;
+    let timer;
+    const settle = (reply) => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        socket.destroy();
+        resolve(reply);
+    };
+    const armTimer = (timeoutMs, waitingFor) => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            logger?.(`Daemon probe on ${socketPath} timed out after ${timeoutMs}ms ${waitingFor}`);
+            settle(null);
+        }, timeoutMs);
+    };
+    armTimer(SOCKET_CONNECT_TIMEOUT_MS, 'waiting for a connection');
+    socket.on('error', (error) => {
+        // ECONNREFUSED, ENOENT or a mid-reply reset: nothing to talk to.
+        logger?.(`Daemon probe on ${socketPath} failed: ${error.code ?? error.message}`);
+        settle(null);
+    });
+    socket.on('connect', () => {
+        armTimer(SOCKET_REPLY_TIMEOUT_MS, `waiting for a reply to ${command.method}`);
+        const transport = new PipeTransport(socket, socket, puppeteerLogger);
+        transport.onmessage = (message) => settle(message);
+        transport.send(JSON.stringify(command));
+    });
+    return await promise;
+}
+/**
+ * Make the session safe to start a daemon in.
+ *
+ * Returns `true` when a live daemon already serves the session — the caller
+ * should simply wait for it to become ready — and `false` when the caller
+ * should fork one. Any daemon that the pid file does not mention, and any
+ * process group left behind by a daemon that died without cleaning up, is gone
+ * by the time this resolves.
+ */
+export async function ensureCleanStart(sessionId) {
+    const pid = getDaemonPid(sessionId);
+    if (pid !== null) {
+        if (isProcessAlive(pid)) {
+            return true;
+        }
+        // The pid file outlived its daemon. Everything the daemon spawned — MCP
+        // server, browser, Chrome helpers — shares its process group, and the group
+        // still exists as long as one member does, so this single kill reaps the
+        // tree that a SIGKILLed daemon left behind.
+        logger?.(`Pid file names the dead daemon ${pid}; reaping its process group`);
+        killStaleDaemon(pid);
+    }
+    const reply = await probeSocket(sessionId, { method: 'status' });
+    const hiddenPid = reply === null ? null : readPidFromStatus(reply);
+    if (hiddenPid !== null) {
+        logger?.(`Found daemon ${hiddenPid}, which the pid file does not mention; stopping it`);
+        await probeSocket(sessionId, { method: 'stop' });
+        if (!(await waitForProcessExit(hiddenPid, STOP_WAIT_TIMEOUT_MS))) {
+            // It took the request and did not go. Leaving it is precisely the
+            // invisible orphan this probe exists to remove - the caller is about to
+            // fork a daemon that will unlink its socket - so stop asking.
+            logger?.(`Daemon ${hiddenPid} ignored stop; killing its process group`);
+            killStaleDaemon(hiddenPid);
+            await waitForProcessExit(hiddenPid, STOP_WAIT_TIMEOUT_MS);
+        }
+    }
+    // Nothing owns the session now. Drop a stale exit reason so a later failure
+    // is not reported with a previous daemon's explanation. This is the only
+    // place the reason is cleared: `readExitReason` deliberately leaves it in
+    // place, because the CLI's readiness loop reads it on every retry and reports
+    // its *last* error — a read that consumed the file would hand the user a
+    // "Daemon is not running." with no explanation.
+    try {
+        fs.rmSync(exitReasonPath(sessionId), { force: true });
+    }
+    catch {
+        // best-effort
+    }
+    return false;
+}
+/** The file a daemon leaves behind to explain its own exit. */
+function exitReasonPath(sessionId) {
+    return path.join(getRuntimeHome(sessionId), EXIT_REASON_FILE);
+}
+/**
+ * Record why a daemon is going away, for the next CLI invocation to surface.
+ * Best-effort: the daemon is on its way out, and a reason file that cannot be
+ * written must not be the thing that keeps it alive.
+ */
+export function writeExitReason(sessionId, message) {
+    try {
+        fs.writeFileSync(exitReasonPath(sessionId), message);
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * The daemon's exit reason, if it left one. Left in place on purpose: a readiness
+ * loop reads this on every retry and reports its last error, so the file is only
+ * cleared where the session is known clean — `ensureCleanStart`, before a new
+ * daemon is forked. Any caller that reads the reason without that having run
+ * will keep seeing it; that is the invariant, not a leak.
+ */
+export function readExitReason(sessionId) {
+    try {
+        return fs.readFileSync(exitReasonPath(sessionId), 'utf-8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=daemonLifecycle.js.map

package/build/src/opera/daemonLog.js

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { getRuntimeHome } from '../daemon/utils.js';
+import { logger } from '../utils/logger.js';
+import { readExitReason } from './daemonLifecycle.js';
+/**
+ * The daemon's own stdout/stderr capture point, inside the session's runtime
+ * home.
+ */
+export function getDaemonLogPath(sessionId) {
+    return path.join(getRuntimeHome(sessionId), 'daemon.log');
+}
+/**
+ * The log of the daemon before the current one. The log is rotated rather than
+ * truncated — the CLI points at it when a daemon was killed — so this is where a
+ * killed daemon's output lives once the session has started a new one.
+ */
+export function getPreviousDaemonLogPath(sessionId) {
+    return `${getDaemonLogPath(sessionId)}.prev`;
+}
+/**
+ * Open the daemon's log for the spawn, creating the runtime directory the daemon
+ * would otherwise create itself.
+ *
+ * The directory is chmod-ed after creation rather than relying on `mkdirSync`'s
+ * mode, which is masked by the umask and does nothing at all to a directory that
+ * already exists. The daemon refuses to run on a group/world-writable runtime
+ * directory, so the mode has to hold whether the CLI or the daemon created it.
+ *
+ * Nothing here is allowed to stop the daemon from starting: a log is a
+ * diagnostic, and a runtime dir this process cannot write (another user's, a
+ * read-only mount) degrades to `'ignore'` stdio with a warning instead of
+ * killing the spawn. `O_NOFOLLOW` so a planted symlink is never written
+ * through — the pid file gets the same guarantee.
+ */
+export function openDaemonLog(sessionId) {
+    try {
+        const logPath = getDaemonLogPath(sessionId);
+        const dir = path.dirname(logPath);
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (process.platform !== 'win32') {
+            fs.chmodSync(dir, 0o700);
+        }
+        // Rotate instead of truncating: this file is where a killed daemon's output
+        // lives, and the CLI points at it when a daemon left no reason behind.
+        // Keeping one previous generation bounds the growth without throwing away
+        // the only evidence of the previous failure.
+        try {
+            fs.renameSync(logPath, getPreviousDaemonLogPath(sessionId));
+        }
+        catch {
+            // No previous log — the common case.
+        }
+        return fs.openSync(logPath, fs.constants.O_WRONLY |
+            fs.constants.O_CREAT |
+            fs.constants.O_APPEND |
+            fs.constants.O_NOFOLLOW, 0o600);
+    }
+    catch (error) {
+        logger?.('Could not open the daemon log; the daemon will run without one:', error);
+        return 'ignore';
+    }
+}
+/**
+ * Why the daemon is gone, for a command that was already in flight.
+ *
+ * A daemon that ran its own teardown leaves a reason; one that was killed
+ * cannot, and that difference is the whole point of the message. `readExitReason`
+ * leaves the file in place, so this can be called on every attempt.
+ */
+export function daemonExitMessage(sessionId) {
+    const reason = readExitReason(sessionId);
+    if (reason) {
+        return `Daemon exited while running the command: ${reason}`;
+    }
+    return ('Daemon exited while running the command and left no reason behind, ' +
+        'which means it was killed rather than shut down (SIGKILL, the OOM killer). ' +
+        `Its output is at ${getDaemonLogPath(sessionId)}` +
+        `, or at ${getPreviousDaemonLogPath(sessionId)} if a daemon has started since.`);
+}
+/**
+ * The rejection a spawn failure deserves, for `Promise.race` against the
+ * pid-file wait.
+ *
+ * A spawn that fails outright — a missing script, an unusable execPath — emits
+ * `'error'` and never creates the pid file, which would otherwise surface as an
+ * unexplained ready-timeout. The log names the reason; this names the log.
+ */
+export function nameSpawnFailure(child, sessionId) {
+    return new Promise((_, reject) => {
+        child.on('error', error => {
+            reject(new Error(`Failed to start the daemon: ${error.message}. Its log is at ${getDaemonLogPath(sessionId)}.`, { cause: error }));
+        });
+    });
+}
+//# sourceMappingURL=daemonLog.js.map

package/build/src/opera/daemonPidFile.js

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * The daemon's pid file, behind an `O_EXCL` claim.
+ *
+ * Upstream opens the file with `O_TRUNC`, which makes the pid file a last-writer
+ * -wins slot rather than a lock: two clients that both observe "not running"
+ * both spawn a daemon, the second one truncates the first one's file and then
+ * unlinks its socket, and the session is left with one visible daemon and one
+ * deaf one. `O_EXCL` makes exactly one of them the owner; the loser gets
+ * `EEXIST` and exits before it can touch anything.
+ *
+ * A file left by a daemon that died is still reclaimable, but only after
+ * re-reading it to confirm it names that same dead pid: a third daemon may have
+ * claimed it in between. The re-read *narrows* the window to the gap between
+ * that comparison and the unlink — microseconds, and the loser of any race here
+ * retries `O_EXCL` and exits, so it does not close it outright.
+ */
+import fs from 'node:fs';
+import { constants, openSync } from 'node:fs';
+import process from 'node:process';
+import { getDaemonPid, getPidFilePath } from '../daemon/utils.js';
+const PID_FILE_FLAGS = constants.O_WRONLY |
+    constants.O_CREAT |
+    constants.O_EXCL |
+    constants.O_NOFOLLOW;
+/**
+ * Remove the pid file of a daemon that is no longer alive. False when the file
+ * belongs to a live daemon, or to one that is mid-write and has not written its
+ * pid yet — unlinking either would hide a daemon that is starting up.
+ */
+function reclaimStalePidFile(sessionId) {
+    const pidFilePath = getPidFilePath(sessionId);
+    const existingPid = getDaemonPid(sessionId);
+    if (existingPid === null) {
+        return false;
+    }
+    try {
+        process.kill(existingPid, 0);
+        return false;
+    }
+    catch {
+        // Dead pid: the file is ours to reclaim.
+    }
+    try {
+        if (fs.readFileSync(pidFilePath, 'utf-8').trim() !== existingPid.toString()) {
+            return false;
+        }
+        fs.unlinkSync(pidFilePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Open the session's pid file and return the descriptor to write this process's
+ * pid into. Throws — the daemon is expected to report and exit — if another
+ * daemon owns it.
+ *
+ * `O_NOFOLLOW` means a symlink is never followed, and the returned descriptor
+ * is created `0o600`: readable and writable by its owner alone.
+ */
+export function claimPidFile(sessionId) {
+    const pidFilePath = getPidFilePath(sessionId);
+    try {
+        return openSync(pidFilePath, PID_FILE_FLAGS, 0o600);
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST' ||
+            !reclaimStalePidFile(sessionId)) {
+            throw err;
+        }
+    }
+    // One retry: the window between the unlink and this open is nanoseconds, so a
+    // second `EEXIST` means another daemon genuinely won the race.
+    return openSync(pidFilePath, PID_FILE_FLAGS, 0o600);
+}
+//# sourceMappingURL=daemonPidFile.js.map

package/build/src/opera/daemonShutdown.js

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * How the daemon goes away, and what it says about it.
+ *
+ * Two problems, both about the daemon's last words. Every shutdown path has to
+ * record *why* it is leaving — the CLI reads that reason when a command was in
+ * flight, and a shutdown that records nothing is reported there as a kill — and
+ * the handlers that do it have to exist before anything can go wrong, which is
+ * why the daemon installs them next to its other startup work rather than deep
+ * in its teardown.
+ *
+ * A shutdown on request is not a kill: `SIGTERM` from a supervisor, `SIGINT`
+ * from a terminal and `SIGHUP` from a closed shell each name themselves, so
+ * "left no reason behind" is left to mean what it says — a `SIGKILL` or the OOM
+ * killer, neither of which can run a handler at all.
+ */
+import process from 'node:process';
+import { writeExitReason } from './daemonLifecycle.js';
+/** Every signal the daemon treats as "stop", and the words it reports them with. */
+const SHUTDOWN_SIGNALS = [
+    ['SIGTERM', 'terminated by signal: SIGTERM'],
+    ['SIGINT', 'interrupted by signal: SIGINT'],
+    ['SIGHUP', 'hung up on signal: SIGHUP'],
+];
+function describeError(kind, error) {
+    return `${kind}: ${error instanceof Error ? error.message : String(error)}`;
+}
+/**
+ * Install the daemon's signal and uncaught-error handlers.
+ *
+ * The stack goes to stderr rather than `logger` because stderr *is* the daemon
+ * log (stdio is redirected to it at spawn), and a `logger` stream would be
+ * dropped by the `process.exit` the teardown ends in.
+ */
+export function installShutdownHandlers(handlers) {
+    for (const [signal, reason] of SHUTDOWN_SIGNALS) {
+        process.on(signal, () => {
+            void handlers.onSignal(reason);
+        });
+    }
+    process.on('uncaughtException', error => {
+        console.error('[MCP Daemon] Uncaught exception:', error);
+        void handlers.onException(describeError('uncaught exception', error));
+    });
+    process.on('unhandledRejection', error => {
+        console.error('[MCP Daemon] Unhandled rejection:', error);
+        void handlers.onException(describeError('unhandled rejection', error));
+    });
+}
+/**
+ * Record why a daemon is going away, for the next CLI invocation to surface.
+ * Best-effort: the daemon is on its way out, and a reason file that cannot be
+ * written must not be the thing that keeps it alive. A shutdown with no reason
+ * to give writes nothing.
+ */
+export function recordShutdownReason(sessionId, reason) {
+    if (reason) {
+        writeExitReason(sessionId, reason);
+    }
+}
+//# sourceMappingURL=daemonShutdown.js.map

package/build/src/opera/daemonSocket.js

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * The daemon's socket edges: the frame it is answering (`dispatchSocketMessage`,
+ * which routes a streaming request through `answerSocketMessage`), and the
+ * failure it reports when it cannot start listening at all.
+ *
+ * Both exist because the daemon's own error handling is a trapdoor. A frame that
+ * is not JSON rejects the transport callback, and the daemon's
+ * `unhandledRejection` handler runs `cleanup(1)`: one malformed byte from
+ * anything that can open the socket takes the whole session down. And a startup
+ * failure that runs `cleanup()` unlinks the socket file — which, when the
+ * failure is a lost bind race, belongs to the daemon that won. The winner is
+ * left alive and deaf, which is the orphan this whole area exists to prevent.
+ */
+import { randomUUID } from 'node:crypto';
+import process from 'node:process';
+import { writeExitReason } from './daemonLifecycle.js';
+import { withLogSink } from './daemonStreaming.js';
+/**
+ * Parse one framed socket message and hand it to `handle`, answering with an
+ * error reply when it is not JSON — or when `handle` itself throws. The reply is
+ * a reply, not an exception: the caller sends it and closes the connection, and
+ * nothing on this path is allowed to reach the daemon's `unhandledRejection`
+ * handler, whose answer to any stray rejection is to tear the session down.
+ */
+export async function answerSocketMessage(raw, handle) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { success: false, error: 'malformed message' };
+    }
+    try {
+        return await handle(parsed);
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Answer one framed socket message, streaming requests included.
+ *
+ * A streaming request is the `invoke_tool` variant that opted in, and it gets a
+ * token of its own: the chunks it produces are written to this connection as
+ * they arrive, and the same final response frame follows. Two connections may
+ * stream at once, so the token is what keeps their chunks apart — see
+ * `opera/daemonStreaming.ts`. Every other message goes straight to `handle`.
+ */
+export async function dispatchSocketMessage(raw, transport, handle) {
+    return answerSocketMessage(raw, message => {
+        if (message.method === 'invoke_tool' && message.stream === true) {
+            const streamToken = randomUUID();
+            return withLogSink(streamToken, chunk => {
+                transport.send(JSON.stringify({ log: chunk }));
+            }, () => handle(message, streamToken));
+        }
+        return handle(message);
+    });
+}
+/**
+ * Report why the daemon could not start, and get out of the way.
+ *
+ * A daemon that lost the bind race must not run the caller's `teardown`: it
+ * would unlink the socket file the winner is listening on and leave a live,
+ * unreachable daemon behind. It exits bare instead, leaving a reason for the
+ * next CLI invocation to surface. A failure after a successful bind is ours to
+ * clean up, socket and all — and it records why, like every other shutdown.
+ */
+export async function reportStartupFailure(error, options) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (options.socketBound) {
+        await options.teardown(`startup failed: ${detail}`);
+        return;
+    }
+    writeExitReason(options.sessionId, `socket bind failed: ${detail}`);
+    process.exit(1);
+}
+//# sourceMappingURL=daemonSocket.js.map