import type { BrowserObservationPort } from "../application/BrowserObservationPort.js"; import type { ProviderIdentity, ExecutionOptions, } from "../application/AnalysisProvider.js"; import { sanitizeBrowserUrl, type InspectWebPageInput, type ListBrowserTargetsInput, } from "../domain/browserObservation.js"; import { browserTargetListSchema, webPageInspectionSchema, type BrowserTargetList, type WebPageInspection, } from "../domain/browserObservationSchemas.js"; import { IsolatedWebBundleAnalyzer, type WebBundleAnalysisAdmission, } from "./IsolatedWebBundleAnalyzer.js"; import { sourceMapsWithCaptureExclusions } from "../domain/webSourceMapCoverage.js"; import type { AnalyzeWebBundleInput, WebBundleAnalysis, WebSourceMaps, } from "../domain/webBundleAnalysis.js"; import { webObservationSessionSchema, type ObserveWebSessionInput, type WebObservationSession, } from "../domain/browserSession.js"; import { webMcpDiscoverySchema, type DiscoverWebMcpToolsInput, type WebMcpDiscovery, } from "../domain/webMcpDiscovery.js"; import { browserCaptureComparisonSchema, compareBrowserCaptures, type BrowserCaptureComparison, type BrowserCaptureComparisonInput, } from "../domain/browserCaptureComparison.js"; import { webScreenshotDiffSchema, webScreenshotSchema, type CaptureWebScreenshotInput, type CompareWebScreenshotsInput, type WebScreenshot, type WebScreenshotDiff, } from "../domain/webScreenshot.js"; import { AnalysisError, type AnalysisPartialObservation, } from "../domain/analysisErrorBase.js"; import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js"; import { AnalysisCancelledError, AnalysisInputError, } from "../domain/analysisErrorCore.js"; import { BrowserObservationError } from "../domain/browserObservationError.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; import { ProviderCleanupError } from "../domain/providerCleanupError.js"; import type { BrowserObservationOperation } from "../domain/browserObservationErrors.js"; import { err, ok, type Result } from "../domain/result.js"; import { hasCdpTargetWebSocket, type CdpEndpointDiscovery, type CdpEndpointTarget, } from "./CdpEndpoint.js"; import { attachCdpTargetSession, closeCdpTargetSession, openCdpEndpoint, openCdpTargetSession, type CdpTargetSession, } from "./CdpTargetSession.js"; import { capturePage, type CapturedPage } from "./CdpPageCapture.js"; import { selectedCdpCommandTimeoutMs, selectedCdpDiscoveryTimeoutMs, } from "../domain/browserDeadline.js"; import { fetchWebSourceMaps } from "./WebSourceMapFetcher.js"; import { authorizeCdpTarget } from "./CdpAuthorizedTarget.js"; import { observeCdpSession } from "./CdpObservationSession.js"; import { discoverWebMcp } from "./CdpWebMcpDiscovery.js"; import { captureCdpScreenshot } from "./CdpScreenshot.js"; import { comparePngScreenshots } from "./PngVisualDiff.js"; import { CDP_BROWSER_PROVIDER_IDENTITY } from "./providerIdentities.js"; import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js"; import { CdpTargetSessionOwner, bindCdpTransportCleanup, } from "./CdpTargetSessionOwner.js"; const CLEANUP_DOMAINS = [ "Network", "Debugger", "Runtime", "Page", "WebMCP", ] as const; /** Passive browser observation through a selected user-owned CDP endpoint. */ export class CdpBrowserProvider implements BrowserObservationPort { readonly #owner = new CdpTargetSessionOwner(); readonly #bundleAnalyzer: IsolatedWebBundleAnalyzer; #activeOperations = 0; #closing = false; #closePromise: Promise | undefined; readonly #idleWaiters = new Set<() => void>(); constructor(admission?: WebBundleAnalysisAdmission) { this.#bundleAnalyzer = new IsolatedWebBundleAnalyzer(undefined, admission); } async close(): Promise { this.#closing = true; this.#closePromise ??= this.#closeResources().catch((cause: unknown) => { this.#closePromise = undefined; throw cause; }); return await this.#closePromise; } async #closeResources(): Promise { const outcomes = await Promise.allSettled([ this.#closeTransports(), this.#bundleAnalyzer.close(), ]); const failures = outcomes.flatMap((outcome) => outcome.status === "rejected" ? [outcome.reason as unknown] : [], ); if (failures.length === 1) throw failures[0]; if (failures.length > 1) { const typed = failures.filter( (failure): failure is AnalysisError => failure instanceof AnalysisError, ); throw new ProviderCleanupError( CDP_BROWSER_PROVIDER_IDENTITY.id, typed.flatMap((failure) => failure.cleanupResources), { reason: "Browser transport and analyzer cleanup remain incomplete" }, { operation: "analyze_web_bundle", cause: new AggregateError(failures), }, ).bindCleanupDependencies(typed); } } async #closeTransports(): Promise { while (this.#activeOperations > 0) await new Promise((resolve) => this.#idleWaiters.add(resolve)); await this.#owner.close(); } async #withAdmission( operation: BrowserObservationOperation, work: () => Promise>, ): Promise> { if (this.#closing) return err( new ProviderAdapterError(CDP_BROWSER_PROVIDER_IDENTITY.id, operation, { diagnostics: { reason: "provider_closed" }, userMessage: "Browser provider is closed to new observations.", }), ); this.#activeOperations += 1; try { return await work(); } finally { this.#activeOperations -= 1; if (this.#activeOperations === 0) { for (const resolve of this.#idleWaiters) resolve(); this.#idleWaiters.clear(); } } } identity(): ProviderIdentity { return CDP_BROWSER_PROVIDER_IDENTITY; } async listTargets( input: ListBrowserTargetsInput, options: ExecutionOptions = {}, ): Promise> { return await this.#withAdmission("list_browser_targets", () => this.#listTargets(input, options), ); } async #listTargets( input: ListBrowserTargetsInput, options: ExecutionOptions, ): Promise> { try { const endpoint = await openCdpEndpoint( input.cdp_endpoint, "list_browser_targets", options.signal, selectedCdpDiscoveryTimeoutMs(input.discovery_timeout_ms), this.#owner, undefined, { reuseBrowserSocket: true }, ); if (endpoint.connection !== undefined) { if (endpoint.reusableBrowserSocket === true) await this.#owner.releaseBrowserSocket(endpoint.connection); else await this.#owner.finish(endpoint.connection); } const { discovery } = endpoint; const selected = selectTargets( discovery, input.allowed_origins.length === 0 ? undefined : new Set(input.allowed_origins), ); return ok( browserTargetListSchema.parse({ browser: discovery.version, targets: selected.allowed, excluded: selected.excluded, limitations: [ ...(discovery.limitations ?? []), input.allowed_origins.length === 0 ? "All page targets with supported HTTP(S) URLs and a validated CDP transport are listed." : "Only page targets with a validated CDP transport whose current URL matches an explicitly requested exact origin are listed.", ...(selected.unconnectable === 0 ? [] : [ `${String(selected.unconnectable)} otherwise allowed page target(s) lacked a validated direct CDP WebSocket and were excluded.`, ]), ...(selected.allowed.some((target) => target.attached === null) ? [ "CDP discovery could not establish debugger attachment state for one or more targets.", ] : []), ], }), ); } catch (cause: unknown) { return err(providerError(cause, "list_browser_targets", options.signal)); } } async inspectPage( input: InspectWebPageInput, options: ExecutionOptions = {}, ): Promise> { return await this.#withAdmission("inspect_web_page", () => this.#inspectPage(input, options), ); } async #inspectPage( input: InspectWebPageInput, options: ExecutionOptions, ): Promise> { try { const captured = await this.#capture(input, options, "inspect_web_page"); return ok(webPageInspectionSchema.parse(captured.inspection)); } catch (cause: unknown) { return err(providerError(cause, "inspect_web_page", options.signal)); } } async analyzeBundle( input: AnalyzeWebBundleInput, options: ExecutionOptions = {}, ): Promise> { return await this.#withAdmission("analyze_web_bundle", () => this.#analyzeBundle(input, options), ); } async #analyzeBundle( input: AnalyzeWebBundleInput, options: ExecutionOptions, ): Promise> { const admission = await this.#bundleAnalyzer.reserve(); if (!admission.ok) return admission; let captured: CapturedPage | undefined; try { captured = await this.#capture(input, options, "analyze_web_bundle"); let sourceMaps: WebSourceMaps | undefined; if (input.fetch_source_maps) { const fetched = await fetchWebSourceMaps( captured.sourceMapRequests, { ...input, allowed_origins: input.allowed_origins.length > 0 ? input.allowed_origins : [captured.inspection.target.origin], }, options.signal, ); if (!fetched.ok) { const partial = fetched.error.partialObservation; if ( partial !== undefined && "kind" in partial && partial.kind === "web-source-map-fetch" ) fetched.error.partialObservation = { kind: "web-bundle-acquisition", inspection: captured.inspection, source_maps: sourceMapsWithCaptureExclusions( partial.source_maps, captured.inspection.completeness.excluded, ), analysis_status: "not_performed", }; else fetched.error.retainPartialObservation(captured.inspection); return err(fetched.error); } sourceMaps = sourceMapsWithCaptureExclusions( fetched.value, captured.inspection.completeness.excluded, ); } return await this.#bundleAnalyzer.analyze( captured.inspection, sourceMaps ?? { status: "not_requested", requested: 0, processed: 0, items: [], }, input, options.signal, ); } catch (cause: unknown) { // Capture and analyzer work can still throw the exact caller reason. if (options.signal?.aborted === true && cause === options.signal.reason) { return err( new AnalysisCancelledError("analyze_web_bundle", { cause, ...(captured === undefined ? {} : { partialObservation: captured.inspection }), }), ); } return err(providerError(cause, "analyze_web_bundle", options.signal)); } finally { this.#bundleAnalyzer.releaseReservation(); } } async observeSession( input: ObserveWebSessionInput, options: ExecutionOptions = {}, ): Promise> { return await this.#withAdmission("observe_web_session", () => this.#observeSession(input, options), ); } async #observeSession( input: ObserveWebSessionInput, options: ExecutionOptions, ): Promise> { try { return ok( webObservationSessionSchema.parse( await withTargetSession( input, "observe_web_session", options, observeCdpSession, this.#owner, ), ), ); } catch (cause: unknown) { return err(providerError(cause, "observe_web_session", options.signal)); } } async discoverWebMcpTools( input: DiscoverWebMcpToolsInput, options: ExecutionOptions = {}, ): Promise> { return await this.#withAdmission("discover_webmcp_tools", () => this.#discoverWebMcpTools(input, options), ); } async #discoverWebMcpTools( input: DiscoverWebMcpToolsInput, options: ExecutionOptions, ): Promise> { try { return ok( webMcpDiscoverySchema.parse( await withTargetSession( input, "discover_webmcp_tools", options, discoverWebMcp, this.#owner, ), ), ); } catch (cause: unknown) { return err(providerError(cause, "discover_webmcp_tools", options.signal)); } } async compareCaptures( input: BrowserCaptureComparisonInput, ): Promise> { try { return ok( browserCaptureComparisonSchema.parse(compareBrowserCaptures(input)), ); } catch (cause: unknown) { return err(providerError(cause, "compare_web_captures")); } } async captureScreenshot( input: CaptureWebScreenshotInput, options: ExecutionOptions = {}, ): Promise> { return await this.#withAdmission("capture_web_screenshot", () => this.#captureScreenshot(input, options), ); } async #captureScreenshot( input: CaptureWebScreenshotInput, options: ExecutionOptions, ): Promise> { try { return ok( webScreenshotSchema.parse( await withTargetSession( input, "capture_web_screenshot", options, captureCdpScreenshot, this.#owner, ), ), ); } catch (cause: unknown) { return err( providerError(cause, "capture_web_screenshot", options.signal), ); } } async compareScreenshots( input: CompareWebScreenshotsInput, ): Promise> { try { return ok(webScreenshotDiffSchema.parse(comparePngScreenshots(input))); } catch (cause: unknown) { if (cause instanceof TypeError) return err( new AnalysisInputError("compare_web_screenshots", { cause }, [ { path: [], reason: "invalid_format", message: cause.message }, ]), ); return err(providerError(cause, "compare_web_screenshots")); } } async #capture( input: InspectWebPageInput, options: ExecutionOptions, operation: "inspect_web_page" | "analyze_web_bundle", ): Promise { return await withTargetSession( input, operation, options, async (session) => await capturePage({ ...session, operation }), this.#owner, (captured) => captured.inspection, ); } } /** Facts and transport handed to one target operation. */ interface CdpTargetOperationSession { readonly connection: CdpTargetSession["connection"]; readonly sessionId: CdpTargetSession["sessionId"]; readonly discovery: CdpEndpointDiscovery; readonly target: CdpEndpointTarget; readonly input: Input; readonly signal?: AbortSignal; readonly progress?: NonNullable; } /** Authorize one discovered target, run work in its session, and release or close REA's socket. */ const withTargetSession = async < Input extends Pick< InspectWebPageInput, | "cdp_endpoint" | "target_id" | "allowed_origins" | "discovery_timeout_ms" | "command_timeout_ms" >, Output, >( input: Input, operation: BrowserObservationOperation, options: ExecutionOptions, work: (session: CdpTargetOperationSession) => Promise, owner: CdpTargetSessionOwner, partialObservation?: (output: Output) => AnalysisPartialObservation, ): Promise => { const discoveryTimeoutMs = selectedCdpDiscoveryTimeoutMs( input.discovery_timeout_ms, ); const commandTimeoutMs = selectedCdpCommandTimeoutMs( input.command_timeout_ms, ); const endpoint = await openCdpEndpoint( input.cdp_endpoint, operation, options.signal, discoveryTimeoutMs, owner, commandTimeoutMs, { reuseBrowserSocket: true }, ); let targetSession: CdpTargetSession | undefined; let attachAttempted = false; let outcome: Result; let cleanupFailure: AnalysisError | undefined; try { const { target, allowedOrigins } = authorizeCdpTarget( endpoint.discovery, input, operation, ); // The authorization owner already derived the target origin scope. const scopedInput = input.allowed_origins.length > 0 ? input : { ...input, allowed_origins: [...allowedOrigins] }; if (endpoint.connection === undefined) { targetSession = await openCdpTargetSession( endpoint.discovery, target, operation, options.signal, { commandTimeoutMs }, owner, ); } else { attachAttempted = true; targetSession = await attachCdpTargetSession( endpoint.connection, target, operation, options.signal, owner, ); } outcome = ok( await work({ connection: targetSession.connection, sessionId: targetSession.sessionId, discovery: endpoint.discovery, target, input: scopedInput, ...(options.signal === undefined ? {} : { signal: options.signal }), ...(options.progress === undefined ? {} : { progress: options.progress }), }), ); } catch (cause: unknown) { outcome = err(cause); } try { if (targetSession !== undefined) await closeCdpTargetSession( targetSession, CLEANUP_DOMAINS, options.signal, owner, endpoint.reusableBrowserSocket === true, ); if ( endpoint.connection !== undefined && endpoint.connection !== targetSession?.connection ) { if (endpoint.reusableBrowserSocket === true) { if (attachAttempted) await owner.evictBrowserSocket(endpoint.connection); else await owner.releaseBrowserSocket(endpoint.connection); } else { await owner.finish(endpoint.connection); } } } catch (cause: unknown) { cleanupFailure = cause instanceof AnalysisError ? cause : new ProviderCleanupError( "rea-cdp-browser", [input.target_id], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation, cause }, ); } if (outcome.ok && options.signal?.aborted === true) outcome = err( partialObservation === undefined ? new AnalysisCancelledError(operation, { cause: options.signal.reason, }) : new AnalysisCancelledError(operation, { cause: options.signal.reason, partialObservation: partialObservation(outcome.value), }), ); if (cleanupFailure !== undefined) { if (!outcome.ok && outcome.error instanceof AnalysisError) throw bindCdpTransportCleanup( cleanupFailure, analysisErrorWithCleanupFailure( outcome.error, cleanupFailure, operation, ), ); if (!outcome.ok) throw new AggregateError( [outcome.error, cleanupFailure], `CDP operation ${operation} failed and cleanup remains incomplete.`, { cause: outcome.error }, ); throw bindCdpTransportCleanup( cleanupFailure, new ProviderCleanupError( "rea-cdp-browser", cleanupFailure.cleanupResources, { cleanup_error: cleanupFailure.message }, { operation, cause: cleanupFailure, ...(partialObservation === undefined ? {} : { partialObservation: partialObservation(outcome.value) }), }, ), ); } if (!outcome.ok) throw outcome.error; return outcome.value; }; const selectTargets = ( discovery: CdpEndpointDiscovery, allowedOrigins: ReadonlySet | undefined, ): { readonly allowed: readonly BrowserTargetList["targets"][number][]; readonly excluded: BrowserTargetList["excluded"]; readonly unconnectable: number; } => { const allowed = []; let disallowedOrigin = 0; let unsupportedUrl = 0; let nonPage = 0; let unconnectable = 0; for (const target of discovery.targets) { if (target.type !== "page") { nonPage += 1; continue; } const url = sanitizeBrowserUrl(target.url); if (url.origin === null) { unsupportedUrl += 1; continue; } if (allowedOrigins !== undefined && !allowedOrigins.has(url.origin)) { disallowedOrigin += 1; continue; } if (!hasCdpTargetWebSocket(discovery, target)) { unconnectable += 1; continue; } allowed.push({ target_id: target.id, type: target.type, title: target.title, url: url.url, origin: url.origin, attached: target.attached, }); } allowed.sort((left, right) => compareUnicodeCodePoints(left.target_id, right.target_id), ); return { allowed, excluded: { disallowed_origin: disallowedOrigin, unsupported_url: unsupportedUrl, non_page: nonPage, }, unconnectable, }; }; const providerError = ( cause: unknown, operation: BrowserObservationOperation, signal?: AbortSignal, ): AnalysisError => cause instanceof BrowserObservationError ? cause.forOperation(operation) : cause instanceof AnalysisError ? cause : signal?.aborted === true ? new AnalysisCancelledError(operation, { cause }) : new ProviderAdapterError( CDP_BROWSER_PROVIDER_IDENTITY.id, operation, { cause, }, );