opera-devtools-mcp 0.7.0 → 0.8.1

package/README.md

@@ -10,7 +10,7 @@ control and inspect a live browser. It acts as a Model-Context-Protocol
 DevTools for reliable automation, in-depth debugging, and performance analysis.
 When connected to Opera Neon, it also exposes Opera's built-in AI capabilities.
 
-## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md)
+## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) | [Design Principles](./docs/design-principles.md) | [Stress testing](./docs/stress-testing.md)
 
 ## Key features
 

package/build/src/ToolHandler.js

@@ -5,10 +5,13 @@
  *
  * Modified by Opera Software AS: optional `hooks` seam (see
  * ./opera/toolHandlerHooks.ts) for mutex bypass, browser relaunch and log
- * streaming. Keep the diff to the three `this.hooks?.` call sites.
+ * streaming, plus one page-resolution call that tolerates a selection the user
+ * closed (see ./opera/pageRecovery.ts). Keep the diff to the three
+ * `this.hooks?.` call sites and that line.
  */
 import { McpResponse } from './McpResponse.js';
 import { CLI_BIN_NAME } from './opera/branding.js';
+import { resolveSelectedPage } from './opera/pageRecovery.js';
 import { SlimMcpResponse } from './SlimMcpResponse.js';
 import { ClearcutLogger } from './telemetry/ClearcutLogger.js';
 import { zod } from './third_party/index.js';
@@ -204,7 +207,7 @@ export class ToolHandler {
                             pageId !== undefined &&
                             !this.serverArgs.slim
                             ? context.getPageById(pageId)
-                            : context.getSelectedMcpPage();
+                            : await resolveSelectedPage(context, response);
                     response.setPage(page);
                     if (this.tool.blockedByDialog) {
                         page.throwIfDialogOpen();
@@ -265,6 +268,10 @@ export class ToolHandler {
             };
         }
         finally {
+            // Before telemetry and the mutex release: the claim `beforeInvoke` took
+            // has to be released even when the invocation failed, or the next Opera
+            // AI tool waits on a browser this one only looks like it is using.
+            this.hooks?.afterInvoke(this.tool);
             void ClearcutLogger.get()?.logToolInvocation({
                 toolName: this.tool.name,
                 params,

package/build/src/bin/chrome-devtools.js

@@ -7,10 +7,14 @@
  * Modified by Opera Software AS.
  */
 import process from 'node:process';
-import { startDaemon, stopDaemon, sendCommand, handleResponse, verifyDaemonVersion, } from '../daemon/client.js';
+import { startDaemon, stopDaemon, sendCommand } from '../daemon/client.js';
 import { isDaemonRunning, serializeArgs, assertValidSessionId, } from '../daemon/utils.js';
 import { logDisclaimers } from '../index.js';
 import { CLI_BIN_NAME, MCP_BIN_NAME, PACKAGE_NAME } from '../opera/branding.js';
+import { describeBrowserMode } from '../opera/browserFlags.js';
+import { EXIT_CODES } from '../opera/cdpErrors.js';
+import { registerOperaCommands, registerToolCommand, } from '../opera/cliCommands.js';
+import { launcherMigrationNotice } from '../opera/launcherNotice.js';
 import { hideBin, yargs } from '../third_party/index.js';
 import { checkForUpdates } from '../utils/check-for-updates.js';
 import { VERSION } from '../version.js';
@@ -19,6 +23,13 @@ import { mcpOptions, parseArguments, getMcpOptionsForViaCli, } from '../config/m
 process.title = CLI_BIN_NAME;
 await checkForUpdates(`Run \`npm install -g ${PACKAGE_NAME}@latest\` and \`${CLI_BIN_NAME} start\` to update and restart the daemon.`);
 const DEFAULT_CLI_ARGS = ['--viaCli'];
+// `--version` is also what a user runs when something looks wrong, so it has to
+// carry the phase-2 recipe when the compatibility launcher is what ran this CLI
+// (`src/opera/launcherNotice.ts`). Without the marker the banner is the plain
+// version, exactly as before.
+const versionBanner = [VERSION, launcherMigrationNotice()]
+    .filter(Boolean)
+    .join('\n\n');
 async function start(args, sessionId) {
     const combinedArgs = [...DEFAULT_CLI_ARGS, ...args];
     await startDaemon(combinedArgs, sessionId);
@@ -52,7 +63,7 @@ const y = yargs(hideBin(process.argv))
     },
 })
     .demandCommand()
-    .version(VERSION)
+    .version(versionBanner)
     .strict()
     .help(true)
     .wrap(120)
@@ -64,20 +75,22 @@ const y = yargs(hideBin(process.argv))
             msg.includes('Unknown arguments')) {
             console.error('\n=========================================');
             console.error('💡 TIP FOR AI AGENT / DEVELOPER:');
-            console.error('In the `chrome-devtools` CLI:');
+            console.error(`In the \`${CLI_BIN_NAME}\` CLI:`);
             console.error('1. Required parameters MUST be passed as positional arguments (without flags).');
-            console.error('   - INCORRECT: chrome-devtools click --pageId 1 --uid "1_2"');
-            console.error('   - CORRECT:   chrome-devtools click 1 "1_2"');
+            console.error(`   - INCORRECT: ${CLI_BIN_NAME} click --pageId 1 --uid "1_2"`);
+            console.error(`   - CORRECT:   ${CLI_BIN_NAME} click 1 "1_2"`);
             console.error('2. Optional parameters are passed as double-dash options/flags (e.g. --dblClick true).');
             console.error('3. Make sure to escape quotes properly for your shell environment.');
-            console.error('Run `chrome-devtools <command> --help` to see exact positional and optional parameters.');
+            console.error(`Run \`${CLI_BIN_NAME} <command> --help\` to see exact positional and optional parameters.`);
             console.error('=========================================');
         }
     }
     else if (err) {
         console.error(err);
     }
-    process.exit(1);
+    // A parse failure is exactly what exit code 2 means — "fix the command" — so
+    // it is reported as one rather than as an unknown failure.
+    process.exit(msg ? EXIT_CODES.VALIDATION_ERROR : EXIT_CODES.UNKNOWN);
 });
 y.command('start', `Start or restart ${MCP_BIN_NAME}`, y => y
     .options(getCliOptions())
@@ -113,9 +126,12 @@ y.command('status', `Checks if ${MCP_BIN_NAME} is running`, y => y, async (argv)
         if (response.success) {
             const data = JSON.parse(response.result);
             console.log(`pid=${data.pid} socket=${data.socketPath} start-date=${data.startDate} version=${data.version}`);
+            // Who owns the browser decides what recovery to expect from it: we
+            // relaunch what we launched, and never touch a browser we attached to.
+            console.log(`browser=${describeBrowserMode(data.args)}`);
             console.log(`args=${JSON.stringify(data.args)}`);
             if (data.version !== VERSION) {
-                console.warn(`Warning: Daemon server version (${data.version}) does not match CLI version (${VERSION}). Run 'chrome-devtools start' to update and restart the daemon.`);
+                console.warn(`Warning: Daemon server version (${data.version}) does not match CLI version (${VERSION}). Run '${CLI_BIN_NAME} start' to update and restart the daemon.`);
             }
         }
         else {
@@ -136,96 +152,13 @@ y.command('stop', `Stop ${MCP_BIN_NAME} if any`, y => y, async (argv) => {
     await stopDaemon(sessionId);
     process.exit(0);
 });
+// The fork's own commands (`setup`, `doctor`, `logs`, `url`) and the wrapper
+// that turns a generated tool definition into a runnable command live in
+// `src/opera/cliCommands.ts`, along with the exit-code and streaming plumbing
+// of a tool call. `start` stays here: it is upstream's, and prepends `--viaCli`.
+registerOperaCommands(y, { start });
 for (const [commandName, commandDef] of Object.entries(commands)) {
-    const args = commandDef.args;
-    const requiredArgNames = Object.keys(args).filter(name => args[name].required);
-    const optionalArgNames = Object.keys(args).filter(name => !args[name].required);
-    let commandStr = commandName;
-    for (const arg of requiredArgNames) {
-        commandStr += ` <${arg}>`;
-    }
-    for (const arg of optionalArgNames) {
-        commandStr += ` [--${arg}]`;
-    }
-    y.command(commandStr, commandDef.description, y => {
-        y.option('output-format', {
-            choices: ['md', 'json'],
-            default: 'md',
-        });
-        for (const [argName, opt] of Object.entries(args)) {
-            const type = opt.type === 'integer' || opt.type === 'number'
-                ? 'number'
-                : opt.type === 'boolean'
-                    ? 'boolean'
-                    : opt.type === 'array'
-                        ? 'array'
-                        : 'string';
-            if (opt.required) {
-                const options = {
-                    describe: opt.description,
-                    type: type,
-                };
-                if (opt.default !== undefined) {
-                    options.default = opt.default;
-                }
-                if (opt.enum) {
-                    options.choices = opt.enum;
-                }
-                y.positional(argName, options);
-            }
-            else {
-                const options = {
-                    describe: opt.description,
-                    type: type,
-                };
-                if (opt.default !== undefined) {
-                    options.default = opt.default;
-                }
-                if (opt.enum) {
-                    options.choices = opt.enum;
-                }
-                y.option(argName, options);
-            }
-        }
-    }, async (argv) => {
-        const sessionId = argv.sessionId;
-        try {
-            const versionWarningPromise = isDaemonRunning(sessionId)
-                ? verifyDaemonVersion(sessionId, VERSION)
-                : Promise.resolve(undefined);
-            if (!isDaemonRunning(sessionId)) {
-                await start(serializeArgs(mcpOptions, argv), sessionId);
-            }
-            const commandArgs = {};
-            for (const argName of Object.keys(args)) {
-                if (argName in argv) {
-                    commandArgs[argName] = argv[argName];
-                }
-            }
-            const response = await sendCommand({
-                method: 'invoke_tool',
-                tool: commandName,
-                args: commandArgs,
-            }, sessionId);
-            if (response.success) {
-                console.log(await handleResponse(JSON.parse(response.result), argv['output-format']));
-            }
-            else {
-                console.error('Error:', response.error);
-            }
-            const versionWarning = await versionWarningPromise;
-            if (versionWarning) {
-                console.warn(versionWarning);
-            }
-            if (!response.success) {
-                process.exit(1);
-            }
-        }
-        catch (error) {
-            console.error('Failed to execute command:', error);
-            process.exit(1);
-        }
-    });
+    registerToolCommand(y, commandName, commandDef, { start });
 }
 await y.parse();
 //# sourceMappingURL=chrome-devtools.js.map

package/build/src/bin/opera-browser-cli.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2026 Opera Software AS.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Opera-named bin entry (see `package.json` `bin`). The implementation lives in
+// the upstream-owned file and is branded via `src/opera/branding.ts`.
+//
+// The guard comes FIRST, and has to stay first: it installs on import, and the
+// imports below it reach `third_party`, whose bundled `debug` reads the
+// `localStorage` global and prints Node's Web Storage warning. An import listed
+// before this one that reaches `third_party` puts the warning back in front of
+// every command's output.
+import { preloadWebStorageWarningGuardInChildren } from '../opera/webStorageWarning.js';
+import { CLI_BIN_NAME } from '../opera/branding.js';
+import { extractTakeoverFlag, preflightBrowser, sessionIdFromArgv, } from '../opera/browserTarget.js';
+import { formatError } from '../opera/cliOutput.js';
+import { autoConfigure, shouldAutoConfigure } from '../opera/config.js';
+import { applyEnvToArgv, loadOperaCliConfig } from '../opera/envConfig.js';
+import { runLegacyMigrationGuard } from '../opera/legacyBridgeCleanup.js';
+/**
+ * Configure a fresh machine in place, without asking. Skips pure queries and
+ * the (future) `setup`/`logs` commands; reports what it did on stderr so a
+ * scripted user sees the same first-run note as opera-browser-cli.
+ */
+function ensureConfigured(argv) {
+    if (!shouldAutoConfigure(argv)) {
+        return;
+    }
+    const command = argv[2];
+    const result = autoConfigure();
+    if (result.status === 'configured') {
+        const ai = result.browser.isNeon
+            ? 'Opera AI available'
+            : 'chat only — install Opera Neon for invoke-do/make/research';
+        process.stderr.write(`configured: ${result.browser.name} (${ai}) — run \`${CLI_BIN_NAME} setup\` to change\n`);
+        return;
+    }
+    if (result.status === 'no-browser' && command !== 'doctor') {
+        process.stderr.write(`hint: no Opera installation found — run \`${CLI_BIN_NAME} setup\`, or set OPERA_CLI_EXECUTABLE_PATH\n`);
+    }
+}
+// Promote ~/.opera-browser-cli/config into process.env (and warn on unknown
+// keys) before the CLI spawns the daemon, which inherits this environment.
+loadOperaCliConfig();
+// A machine that upgraded from the two-package era may still have the old HTTP
+// bridge running, holding port 9225 and a browser of its own. Nothing runs at
+// install time any more — npm ≥12 blocks install scripts unless the user opts in
+// — so this is the path that always runs: the launcher spawns this CLI for every
+// command, `--version` and `--help` included. One file read when there is no
+// bridge; the port probe behind it runs once per boot. Never throws.
+//
+// The home is the *invoking* user's, not `os.homedir()`: under `sudo`, the
+// bridge (and its PID file) belongs to the user who started it.
+await runLegacyMigrationGuard();
+// The daemon cannot import this module before its own static imports reach
+// `third_party`, so the guard travels to it (and to the MCP server it spawns)
+// through NODE_OPTIONS instead.
+preloadWebStorageWarningGuardInChildren();
+// On a machine that has never been configured, detect the installed Opera
+// build and write a config + set OPERA_CLI_* so this first command works.
+ensureConfigured(process.argv);
+// `--takeover` decides how a profile conflict is settled, and belongs to the
+// preflight rather than to any command — every command parser is strict, so it
+// is read and removed before one of them sees it. It is left in the environment
+// because the preflight is not the only place a conflict is settled: a tool
+// call that fails on one settles it too, one process deeper than any argument
+// the command parser kept (`cliCommands.ts`).
+const takeover = extractTakeoverFlag(process.argv);
+if (takeover) {
+    process.env.OPERA_CLI_TAKEOVER = '1';
+}
+// Which browser to drive is decided here, before the command starts a daemon:
+// settling a conflict may need to ask the user, and the daemon is detached with
+// no terminal. The decision travels as OPERA_CLI_* environment, which the
+// daemon and the MCP server it spawns both inherit — and, for `start`, as the
+// flags translated from it immediately below.
+try {
+    await preflightBrowser(process.argv.slice(2), sessionIdFromArgv(process.argv), takeover);
+}
+catch (error) {
+    const { output, exitCode } = await formatError(error);
+    console.error(output);
+    process.exit(exitCode);
+}
+// `start` is the command that decides the daemon's browser options, and its own
+// defaults (`--headless` from the viaCli options, `--isolated`) are serialized
+// as if the user had passed them — so the MCP server bin's `applyEnvToArgv`,
+// which skips a flag already on argv, can no longer see OPERA_CLI_HEADED or
+// OPERA_CLI_USER_DATA_DIR. Translating the environment into explicit flags
+// here, before yargs parses the command, lets the config beat those defaults.
+// Only `start` takes the browser flags; `status`, `stop` and the tool commands
+// have strict parsers that would reject them, and a directly-run MCP server
+// still does the translation in its own bin.
+if (process.argv[2] === 'start') {
+    applyEnvToArgv(process.argv);
+}
+// Dynamic import: static imports are hoisted above the module body, so the
+// config load above would otherwise run after the CLI already parsed argv.
+await import('./chrome-devtools.js');
+//# sourceMappingURL=opera-browser-cli.js.map

package/build/src/bin/opera-devtools-mcp.js

@@ -6,5 +6,24 @@
  */
 // Opera-named bin entry (see `package.json` `bin`). The implementation lives in
 // the upstream-owned file and is branded via `src/opera/branding.ts`.
-import './chrome-devtools-mcp.js';
+import { applyEnvToArgv, loadOperaCliConfig } from '../opera/envConfig.js';
+import { runLegacyMigrationGuard } from '../opera/legacyBridgeCleanup.js';
+// Import for its side effect: silences Node's Web Storage warning before
+// `third_party` reads `localStorage`. See `opera/webStorageWarning.ts`.
+import '../opera/webStorageWarning.js';
+// Apply ~/.opera-browser-cli/config and OPERA_CLI_* env vars before the
+// upstream implementation reads `process.argv`.
+loadOperaCliConfig();
+applyEnvToArgv(process.argv);
+// An MCP client starts this bin directly, with no CLI invocation anywhere, so
+// the migration guard has to run here too: a machine that upgraded from the
+// two-package era may still have the old HTTP bridge (port 9225) holding a
+// browser. Nothing runs at install time — npm ≥12 blocks install scripts unless
+// the user opts in — and this file is also the server the daemon spawns, so both
+// shapes of MCP start are covered. One file read when there is no bridge; the
+// port probe behind it runs once per boot. Never throws, never writes to stdout.
+await runLegacyMigrationGuard();
+// Dynamic import: static imports are hoisted above the module body, so the
+// env/config setup above would otherwise run after the server parsed argv.
+await import('./chrome-devtools-mcp.js');
 //# sourceMappingURL=opera-devtools-mcp.js.map

package/build/src/browser.js

@@ -9,6 +9,8 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { disarmBrowserOrphanCleanup, watchBrowserForOrphans, } from './opera/browserCleanup.js';
+import { attachFailed, noDevToolsEndpoint, profileInUse, } from './opera/browserErrors.js';
 import { puppeteer } from './third_party/index.js';
 import { logger, puppeteerLogger } from './utils/logger.js';
 import { isAllowedUrl } from './utils/url.js';
@@ -73,9 +75,7 @@ export async function ensureBrowserConnected(options) {
                 connectOptions.browserWSEndpoint = browserWSEndpoint;
             }
             catch (error) {
-                throw new Error(`Could not connect to Chrome in ${userDataDir}. Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.`, {
-                    cause: error,
-                });
+                throw new Error(noDevToolsEndpoint(userDataDir), { cause: error });
             }
         }
         else {
@@ -98,9 +98,7 @@ export async function ensureBrowserConnected(options) {
         browser = connected;
     }
     catch (err) {
-        throw new Error(`Could not connect to Chrome. ${autoConnect ? `Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.` : `Check if Chrome is running.`}`, {
-            cause: err,
-        });
+        throw new Error(attachFailed(options, autoConnect), { cause: err });
     }
     logger?.('Connected Puppeteer');
     return browser;
@@ -190,9 +188,10 @@ export async function launch(options) {
     catch (error) {
         if (userDataDir &&
             error.message.includes('The browser is already running')) {
-            throw new Error(`The browser is already running for ${userDataDir}. Use --isolated to run multiple browser instances.`, {
-                cause: error,
-            });
+            // The wording lives in `opera/browserErrors.ts`: upstream's answer to a
+            // profile in use ("use --isolated") is the wrong one for the case that
+            // matters — driving the browser you already have.
+            throw new Error(profileInUse(userDataDir), { cause: error });
         }
         throw error;
     }
@@ -203,6 +202,12 @@ export async function ensureBrowserLaunched(options) {
     }
     // Assign mode before browser; see the connect path above for rationale.
     const launched = await launch(options);
+    // Chrome's helpers sit in the browser's process group, not under it in the
+    // process tree, so a browser that dies without closing — SIGKILL, a crash,
+    // an OOM kill — leaves them running as orphans. `disconnected` is the only
+    // signal that the browser is gone, and the group kill it arms is the only
+    // teardown that reaches the helpers; see `opera/browserCleanup.ts`.
+    watchBrowserForOrphans(launched);
     browserMode = 'launched';
     browser = launched;
     return browser;
@@ -226,6 +231,9 @@ export async function closeBrowser() {
         return;
     }
     if (mode === 'launched') {
+        // The close below emits `disconnected` too; without this the orphan-cleanup
+        // handler would SIGKILL the group mid-shutdown. See `opera/browserCleanup.ts`.
+        disarmBrowserOrphanCleanup();
         await b.close().catch(err => {
             logger?.('Failed to close browser', err);
         });
@@ -237,6 +245,7 @@ export async function closeBrowser() {
 }
 export async function closeBrowserIfOpen() {
     if (browser?.connected) {
+        disarmBrowserOrphanCleanup();
         try {
             await browser.close();
         }

package/build/src/daemon/client.js

@@ -6,9 +6,11 @@
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import net from 'node:net';
-import { PipeTransport } from '../third_party/index.js';
+import { ensureCleanStart, readExitReason } from '../opera/daemonLifecycle.js';
+import { nameSpawnFailure, openDaemonLog } from '../opera/daemonLog.js';
+import { requestOverSocket } from '../opera/daemonStreaming.js';
 import { getTempFilePath } from '../utils/files.js';
-import { logger, puppeteerLogger } from '../utils/logger.js';
+import { logger } from '../utils/logger.js';
 import { DAEMON_SCRIPT_PATH, getSocketPath, getPidFilePath, isDaemonRunning, } from './utils.js';
 const FILE_TIMEOUT = 10_000;
 const READY_CHECK_INTERVAL = 100;
@@ -77,64 +79,68 @@ async function waitForDaemonReady(sessionId) {
     throw new Error(`Timeout: daemon not ready within ${FILE_TIMEOUT}ms`, lastError === undefined ? undefined : { cause: lastError });
 }
 export async function startDaemon(mcpArgs = [], sessionId) {
-    if (isDaemonRunning(sessionId)) {
+    // Not `isDaemonRunning`: that reads the pid file, and a daemon whose pid file
+    // is gone (or whose socket a racing starter unlinked) is invisible to it.
+    // `ensureCleanStart` probes the socket and reaps whatever the last daemon left
+    // behind, so the daemon we are about to fork is the only one in the session.
+    if (await ensureCleanStart(sessionId)) {
         logger?.('Daemon is already running');
         await waitForDaemonReady(sessionId);
         return;
     }
+    logger?.('Starting daemon...', ...mcpArgs);
     const pidFilePath = getPidFilePath(sessionId);
-    if (fs.existsSync(pidFilePath)) {
-        fs.unlinkSync(pidFilePath);
+    const logFd = openDaemonLog(sessionId);
+    let child;
+    try {
+        child = spawn(process.execPath, [DAEMON_SCRIPT_PATH, ...mcpArgs], {
+            detached: true,
+            // Not 'ignore' unless there was nothing to open: the daemon is detached
+            // with no terminal, so discarding its output leaves a daemon that dies
+            // silently unexplainable. The file is what the mid-command failure below
+            // points the user at.
+            stdio: logFd === 'ignore' ? 'ignore' : ['ignore', logFd, logFd],
+            env: { ...process.env, CHROME_DEVTOOLS_MCP_SESSION_ID: sessionId },
+            cwd: process.cwd(),
+            windowsHide: true,
+        });
+    }
+    finally {
+        // The child holds its own descriptor; the parent's copy would outlive it.
+        if (logFd !== 'ignore') {
+            fs.closeSync(logFd);
+        }
     }
-    logger?.('Starting daemon...', ...mcpArgs);
-    const child = spawn(process.execPath, [DAEMON_SCRIPT_PATH, ...mcpArgs], {
-        detached: true,
-        stdio: 'ignore',
-        env: { ...process.env, CHROME_DEVTOOLS_MCP_SESSION_ID: sessionId },
-        cwd: process.cwd(),
-        windowsHide: true,
-    });
     child.unref();
-    await waitForFile(pidFilePath);
+    // The pid file and the spawn's own failure, whichever comes first. See
+    // `opera/daemonLog.ts` for why a failed spawn must not surface as a timeout.
+    await Promise.race([
+        waitForFile(pidFilePath),
+        nameSpawnFailure(child, sessionId),
+    ]);
     await waitForDaemonReady(sessionId);
 }
 const SEND_COMMAND_TIMEOUT = 60_000; // ms
 /**
  * `sendCommand` opens a socket connection sends a single command and disconnects.
+ *
+ * The frame protocol — including `onLog`, which opts the request into the
+ * streaming variant and hands each chunk over as it arrives — lives in
+ * `opera/daemonStreaming.ts`'s `requestOverSocket`.
  */
-export async function sendCommand(command, sessionId, timeout = SEND_COMMAND_TIMEOUT) {
+export async function sendCommand(command, sessionId, timeout = SEND_COMMAND_TIMEOUT, onLog) {
     // Before connecting and sending, verify the daemon is still alive.
     if (!isDaemonRunning(sessionId)) {
-        throw new Error('Daemon is not running.');
+        // A daemon that tore itself down leaves a reason behind; surfacing it is
+        // the difference between "Daemon is not running." and knowing why.
+        const reason = readExitReason(sessionId);
+        throw new Error(reason ? `Daemon is not running: ${reason}` : 'Daemon is not running.');
     }
     const socketPath = getSocketPath(sessionId);
     const socket = net.createConnection({
         path: socketPath,
     });
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            socket.destroy();
-            reject(new Error('Timeout waiting for daemon response'));
-        }, timeout);
-        const transport = new PipeTransport(socket, socket, puppeteerLogger);
-        transport.onmessage = async (message) => {
-            clearTimeout(timer);
-            logger?.('onmessage', message);
-            resolve(JSON.parse(message));
-        };
-        socket.on('error', error => {
-            clearTimeout(timer);
-            logger?.('Socket error:', error);
-            reject(error);
-        });
-        socket.on('close', () => {
-            clearTimeout(timer);
-            logger?.('Socket closed:');
-            reject(new Error('Socket closed'));
-        });
-        logger?.('Sending message', command);
-        transport.send(JSON.stringify(command));
-    });
+    return requestOverSocket({ socket, command, sessionId, timeout, onLog });
 }
 export async function stopDaemon(sessionId) {
     if (!isDaemonRunning(sessionId)) {