feat(browser): attach passive tools to browsers without HTTP discovery

docs/browser-observation.md

@@ -86,6 +86,47 @@ first navigation. For a dedicated investigation profile, add
 then describe an unloaded page; REA continues to require an allowed, committed
 URL. See [the startup investigation](https://github.com/morluto/rea/issues/1384#issuecomment-6093781686).
 
+### Browsers without HTTP discovery
+
+Some browsers expose a loopback browser WebSocket but no `/json/version` or
+`/json/list`. Chrome 144 and later can enable remote debugging on a running
+browser from `chrome://inspect/#remote-debugging`; this mode is reported to
+serve only the browser socket. Since Chrome 136, `--remote-debugging-port` is
+ignored for the default profile, so this is the remaining way to inspect a page
+in an existing profile.
+
+For such a browser, pass the browser socket instead of the HTTP endpoint:
+
+```bash
+rea list-browser-targets ws://127.0.0.1:9222/devtools/browser/<id>
+```
+
+Chrome writes the port and the `/devtools/browser/<id>` path to the
+`DevToolsActivePort` file in its user data directory. REA does not read that
+file for you.
+
+- Only `list_browser_targets`, `inspect_web_page`, `analyze_web_bundle`,
+  `observe_web_session`, `discover_webmcp_tools`, and `capture_web_screenshot`
+  accept a browser socket. Website runtime attribution, Electron inspection,
+  and scenario attach mode still require HTTP discovery.
+- Each call opens one WebSocket and uses it for discovery
+  (`Browser.getVersion`, `Target.getTargets`) and for the selected page.
+  Discovery must finish within the same 10-second deadline as HTTP discovery.
+  Chrome may ask you to approve each connection.
+- The browser identifier controls access to the socket. Evidence records the
+  endpoint as `ws://127.0.0.1:9222/devtools/browser/[REDACTED]`.
+- `browser.revision` is the socket's `Browser.getVersion` value, such as
+  `@e533e98…`. HTTP discovery reports `WebKit-Version`, such as
+  `537.36 (@e533e98…)`.
+- `Target.getTargets` reports whether each target is attached. Chrome's
+  `/json/list` can omit it, so HTTP discovery may report `attached` as `null`.
+- An existing profile can hold many unrelated pages. Target listing returns
+  each eligible page's URL and title, so pass `--allowed-origins` to list only
+  the origins you are investigating.
+
+A browser driven only through `--remote-debugging-pipe` or a vendor's private
+automation channel has neither endpoint, and REA cannot attach to it.
+
 ## Request boundary
 
 CDP connections enforce the shared 64 MiB limit per WebSocket message. A larger
@@ -95,9 +136,13 @@ decoded strings or JSON objects.
 
 Discovery supplies a literal loopback CDP endpoint and returns all eligible
 page targets unless an exact HTTP(S) origin filter narrows the result. Follow-up
-inspection requests select one target; their default scope is its current origin. `localhost`, private-LAN
-addresses, HTTPS CDP endpoints, credentials, paths, queries, fragments, and
-implicit ports are not valid CDP endpoints. Origin filters contain only scheme,
+inspection requests select one target; their default scope is its current origin.
+The endpoint is either `http://127.0.0.1:PORT` or a
+[browser socket](#browsers-without-http-discovery),
+`ws://127.0.0.1:PORT/devtools/browser/ID`; `[::1]` may replace `127.0.0.1`.
+`localhost`, private-LAN addresses, HTTPS and `wss:` endpoints, credentials,
+queries, fragments, implicit ports, and any other path are not valid CDP
+endpoints. Origin filters contain only scheme,
 host, and port; paths, credentials, queries, fragments, and wildcards are not
 valid origins.
 

scripts/lib/browser-socket-e2e.mjs

@@ -0,0 +1,100 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  inspectWebPageInputSchema,
+  listBrowserTargetsInputSchema,
+} from "../../dist/domain/browserObservation.js";
+import { compareWebCapturesInputSchema } from "../../dist/domain/webCaptureDiffSchemas.js";
+import { artifactCliEvidence } from "./artifact-e2e.mjs";
+
+/** Verify browser-socket discovery and inspection against HTTP discovery. */
+export async function verifyBrowserSocketTransport({
+  provider,
+  profile,
+  endpoint,
+  target,
+  origin,
+}) {
+  const [port, path] = (
+    await readFile(join(profile, "DevToolsActivePort"), "utf8")
+  ).split("\n");
+  const socket = `ws://127.0.0.1:${port}${path}`;
+  const version = await (await fetch(`${endpoint}/json/version`)).json();
+  assert.equal(
+    new URL(version.webSocketDebuggerUrl).pathname,
+    path,
+    "DevToolsActivePort and /json/version named different browser sockets",
+  );
+  const list = async (cdpEndpoint) => {
+    const listed = await provider.listTargets(
+      listBrowserTargetsInputSchema.parse({
+        cdp_endpoint: cdpEndpoint,
+        allowed_origins: [origin],
+      }),
+    );
+    if (!listed.ok) throw listed.error;
+    return listed.value;
+  };
+  const throughHttp = await list(endpoint);
+  const throughSocket = await list(socket);
+  // Target.getTargets reports attachment state that /json/list may omit.
+  const withoutAttachment = (targets) =>
+    targets.map(({ attached: _attached, ...rest }) => rest);
+  assert.ok(throughSocket.targets.length > 0, "Browser socket listed no page");
+  assert.deepEqual(
+    withoutAttachment(throughSocket.targets),
+    withoutAttachment(throughHttp.targets),
+  );
+  assert.ok(
+    throughSocket.targets.every(
+      ({ attached }) => typeof attached === "boolean",
+    ),
+    "Browser socket omitted target attachment state",
+  );
+  assert.equal(throughSocket.browser.product, throughHttp.browser.product);
+
+  const evidence = await artifactCliEvidence("inspect-web-page", socket, [
+    target,
+    "--allowed-origins",
+    origin,
+    "--observation-ms",
+    "100",
+  ]);
+  assert.equal(evidence.normalized_result.target.target_id, target);
+  assert.ok(
+    evidence.normalized_result.dom.nodes.length > 0,
+    "Browser-socket inspection returned no DOM nodes",
+  );
+  assert.equal(
+    evidence.parameters.cdp_endpoint,
+    `ws://127.0.0.1:${port}/devtools/browser/[REDACTED]`,
+  );
+  assert.ok(
+    !JSON.stringify(evidence).includes(path),
+    "Browser-socket Evidence retained the socket identifier",
+  );
+  const throughHttpInspection = await provider.inspectPage(
+    inspectWebPageInputSchema.parse({
+      cdp_endpoint: endpoint,
+      allowed_origins: [origin],
+      target_id: target,
+      observation_ms: 100,
+    }),
+  );
+  if (!throughHttpInspection.ok) throw throughHttpInspection.error;
+  const compared = await provider.compareCaptures(
+    compareWebCapturesInputSchema.parse({
+      before: { inspection: throughHttpInspection.value },
+      after: { inspection: evidence.normalized_result },
+    }),
+  );
+  if (!compared.ok) throw compared.error;
+  assert.equal(compared.value.dimensions.dom_structure.status, "unchanged");
+  assert.equal(compared.value.dimensions.scripts.status, "unchanged");
+  return {
+    targets: throughSocket.targets.length,
+    revision: throughSocket.browser.revision,
+  };
+}

scripts/verify-real-browser.mjs

@@ -42,6 +42,7 @@ import { verifyBrowserNetworkEvidence } from "./lib/browser-network-e2e.mjs";
 import { verifyBrowserScriptExport } from "./lib/browser-script-export-e2e.mjs";
 import { verifyBrowserModules } from "./lib/browser-module-e2e.mjs";
 import { verifyBrowserDomDestinations } from "./lib/browser-dom-destinations-e2e.mjs";
+import { verifyBrowserSocketTransport } from "./lib/browser-socket-e2e.mjs";
 import { verifyBrowserCaptureMetadataBudget } from "./lib/browser-capture-metadata-budget-e2e.mjs";
 import { artifactCliEvidence, artifactMcpResult } from "./lib/artifact-e2e.mjs";
 import { verifyScenarioEnvironment } from "./lib/browser-scenario-environment-e2e.mjs";
@@ -232,6 +233,13 @@ try {
 
   pageProxy = await startPageCdpProxy(endpoint);
   await verifyPageScopedTransport(provider, pageProxy, site.origin);
+  const browserSocketTransport = await verifyBrowserSocketTransport({
+    provider,
+    profile,
+    endpoint,
+    target,
+    origin: site.origin,
+  });
   const attachedScenarioInput = browserScenario(
     {
       mode: "connect",
@@ -375,6 +383,7 @@ try {
     bundle_cli_and_stdio_mcp: true,
     sessionEvents: session.value.timeline.length,
     pageScopedTransport: true,
+    browserSocketTransport,
     screenshotBytes: screenshot.value.artifact.bytes,
     largeScreenshot,
     popupEvents,

src/application/BrowserEvidence.ts

@@ -131,7 +131,7 @@ const browserParameters = (
   }
   const observedOrigin = browserResultTargetOrigin(result);
   const scope = {
-    cdp_endpoint: input.cdp_endpoint,
+    cdp_endpoint: input.cdp_endpoint.recorded,
     allowed_origins:
       input.allowed_origins.length > 0
         ? input.allowed_origins