diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ac09b405e..cb1ae8d8d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,7 +13,7 @@ npm run build
npm test
```
-Keep dependencies flowing inward through the existing domain, contracts, provider, application, server, and adapter layers. Parse unknown values at process and protocol boundaries, model expected failures with `Result`, and preserve the 33 direct, 10 enhanced, 5 native, 2 artifact, 2 browser, and 18 session tools (70 total) unless a deliberate contract change updates every verifier and snapshot.
+Keep dependencies flowing inward through the existing domain, contracts, provider, application, server, and adapter layers. Parse unknown values at process and protocol boundaries, model expected failures with `Result`, and preserve the 33 direct, 10 enhanced, 5 native, 2 artifact, 8 browser, 2 Electron, and 18 session tools (78 total) unless a deliberate contract change updates every verifier and snapshot.
Before submitting a pull request, run:
@@ -70,7 +70,7 @@ Publish the public package:
npm publish --access public
```
-After npm registry propagation, verify the published CLI and connect a beta.3 MCP client to the published server to confirm all 70 tools:
+After npm registry propagation, verify the published CLI and connect a beta.3 MCP client to the published server to confirm all 78 tools:
```bash
npx -y rea-agents --help
diff --git a/README.md b/README.md
index 08f341812..9175d6263 100644
--- a/README.md
+++ b/README.md
@@ -10,11 +10,11 @@
[](https://www.npmjs.com/package/rea-agents)
[](https://github.com/morluto/rea/actions/workflows/ci.yml)
-[](#70-tools-for-investigation)
+[](#78-tools-for-investigation)
[](https://nodejs.org/)
[](LICENSE)
-[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [70 tools](#70-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
+[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [78 tools](#78-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
REA browser verifier Browser evidence Verify REA browser verifier Browser evidence Verify >;
+ analyzeBundle(
+ input: AnalyzeWebBundleInput,
+ options?: ExecutionOptions,
+ ): Promise>;
+ observeSession(
+ input: ObserveWebSessionInput,
+ options?: ExecutionOptions,
+ ): Promise>;
+ discoverWebMcpTools(
+ input: DiscoverWebMcpToolsInput,
+ options?: ExecutionOptions,
+ ): Promise>;
+ compareCaptures(
+ input: CompareWebCapturesInput,
+ ): Promise>;
+ captureScreenshot(
+ input: CaptureWebScreenshotInput,
+ options?: ExecutionOptions,
+ ): Promise>;
+ compareScreenshots(
+ input: CompareWebScreenshotsInput,
+ ): Promise>;
}
diff --git a/src/application/BrowserObservationService.ts b/src/application/BrowserObservationService.ts
index 859a33168..6ad7c1f58 100644
--- a/src/application/BrowserObservationService.ts
+++ b/src/application/BrowserObservationService.ts
@@ -3,6 +3,14 @@ import type {
InspectWebPageInput,
ListBrowserTargetsInput,
} from "../domain/browserObservation.js";
+import type { AnalyzeWebBundleInput } from "../domain/webBundleAnalysis.js";
+import type { ObserveWebSessionInput } from "../domain/browserSession.js";
+import type { DiscoverWebMcpToolsInput } from "../domain/webMcpDiscovery.js";
+import type { CompareWebCapturesInput } from "../domain/webCaptureDiff.js";
+import type {
+ CaptureWebScreenshotInput,
+ CompareWebScreenshotsInput,
+} from "../domain/webScreenshot.js";
import {
AnalysisCapabilityUnavailableError,
AnalysisProtocolError,
@@ -69,11 +77,154 @@ export const inspectWebPage = async (
: result;
};
+/** Capture approved sources and derive bounded static web-bundle evidence. */
+export const analyzeWebBundle = async (
+ browser: BrowserObservationPort | undefined,
+ authority: PermissionAuthority | undefined,
+ input: AnalyzeWebBundleInput,
+ options: ExecutionOptions = {},
+): Promise> => {
+ const ready = await prepare(browser, authority, input, "analyze_web_bundle");
+ if (!ready.ok) return ready;
+ const analyzed = await ready.value.analyzeBundle(input, options);
+ if (!analyzed.ok) return analyzed;
+ return ok(
+ createBrowserEvidence(
+ "analyze_web_bundle",
+ input,
+ analyzed.value,
+ ready.value.identity(),
+ ),
+ );
+};
+
+/** Observe navigation caused by external user actions during one armed window. */
+export const observeWebSession = async (
+ browser: BrowserObservationPort | undefined,
+ authority: PermissionAuthority | undefined,
+ input: ObserveWebSessionInput,
+ options: ExecutionOptions = {},
+): Promise> => {
+ const ready = await prepare(browser, authority, input, "observe_web_session");
+ if (!ready.ok) return ready;
+ const observed = await ready.value.observeSession(input, options);
+ return observed.ok
+ ? ok(
+ createBrowserEvidence(
+ "observe_web_session",
+ input,
+ observed.value,
+ ready.value.identity(),
+ ),
+ )
+ : observed;
+};
+
+/** Discover WebMCP declarations without exposing an invocation surface. */
+export const discoverWebMcpTools = async (
+ browser: BrowserObservationPort | undefined,
+ authority: PermissionAuthority | undefined,
+ input: DiscoverWebMcpToolsInput,
+ options: ExecutionOptions = {},
+): Promise> => {
+ const ready = await prepare(
+ browser,
+ authority,
+ input,
+ "discover_webmcp_tools",
+ );
+ if (!ready.ok) return ready;
+ const discovered = await ready.value.discoverWebMcpTools(input, options);
+ return discovered.ok
+ ? ok(
+ createBrowserEvidence(
+ "discover_webmcp_tools",
+ input,
+ discovered.value,
+ ready.value.identity(),
+ ),
+ )
+ : discovered;
+};
+
+/** Compare two already-normalized web captures without external access. */
+export const compareWebCaptureEvidence = async (
+ browser: BrowserObservationPort | undefined,
+ input: CompareWebCapturesInput,
+): Promise> => {
+ const ready = requireBrowser(browser, "compare_web_captures");
+ if (!ready.ok) return ready;
+ const compared = await ready.value.compareCaptures(input);
+ return compared.ok
+ ? ok(
+ createBrowserEvidence(
+ "compare_web_captures",
+ input,
+ compared.value,
+ ready.value.identity(),
+ ),
+ )
+ : compared;
+};
+
+/** Capture one explicitly approved visible-viewport screenshot. */
+export const captureWebScreenshot = async (
+ browser: BrowserObservationPort | undefined,
+ authority: PermissionAuthority | undefined,
+ input: CaptureWebScreenshotInput,
+ options: ExecutionOptions = {},
+): Promise> => {
+ const ready = await prepare(
+ browser,
+ authority,
+ input,
+ "capture_web_screenshot",
+ );
+ if (!ready.ok) return ready;
+ const captured = await ready.value.captureScreenshot(input, options);
+ return captured.ok
+ ? ok(
+ createBrowserEvidence(
+ "capture_web_screenshot",
+ input,
+ captured.value,
+ ready.value.identity(),
+ ),
+ )
+ : captured;
+};
+
+/** Compare two self-verifying PNG artifacts without external access. */
+export const compareWebScreenshotEvidence = async (
+ browser: BrowserObservationPort | undefined,
+ input: CompareWebScreenshotsInput,
+): Promise> => {
+ const ready = requireBrowser(browser, "compare_web_screenshots");
+ if (!ready.ok) return ready;
+ const compared = await ready.value.compareScreenshots(input);
+ return compared.ok
+ ? ok(
+ createBrowserEvidence(
+ "compare_web_screenshots",
+ input,
+ compared.value,
+ ready.value.identity(),
+ ),
+ )
+ : compared;
+};
+
const prepare = async (
browser: BrowserObservationPort | undefined,
authority: PermissionAuthority | undefined,
input: ScopedBrowserInput,
- operation: "list_browser_targets" | "inspect_web_page",
+ operation:
+ | "list_browser_targets"
+ | "inspect_web_page"
+ | "analyze_web_bundle"
+ | "observe_web_session"
+ | "discover_webmcp_tools"
+ | "capture_web_screenshot",
): Promise> => {
if (authority === undefined)
return err(
@@ -115,6 +266,20 @@ const prepare = async (
: ok(browser);
};
+const requireBrowser = (
+ browser: BrowserObservationPort | undefined,
+ operation: string,
+): Result =>
+ browser === undefined
+ ? err(
+ new AnalysisCapabilityUnavailableError(
+ "rea-cdp-browser",
+ operation,
+ "browser comparison provider is not configured",
+ ),
+ )
+ : ok(browser);
+
const browserNetworkScope = (
allowedOrigins: readonly string[],
): "loopback" | "external" =>
diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.ts
index 95e637665..213edefb8 100644
--- a/src/application/CapabilityInventory.ts
+++ b/src/application/CapabilityInventory.ts
@@ -55,6 +55,7 @@ export const buildCapabilityInventory = (
readonly processCaptureEnabled: boolean;
readonly evidenceFileRoots: number;
readonly browserObservationEnabled?: boolean;
+ readonly electronObservationEnabled?: boolean;
},
) => {
const status = statusSchema.parse(sessionStatus);
@@ -99,6 +100,7 @@ const availabilityFor = (
readonly processCaptureEnabled: boolean;
readonly evidenceFileRoots: number;
readonly browserObservationEnabled?: boolean;
+ readonly electronObservationEnabled?: boolean;
},
): {
readonly reason: ToolAvailabilityReason;
@@ -123,6 +125,14 @@ const availabilityFor = (
remediation:
"Enable browser observation and configure exact CDP endpoint and page origins.",
};
+ if (kind === "electron-provider")
+ return policy.electronObservationEnabled === true
+ ? { reason: "available", remediation: null }
+ : {
+ reason: "policy_disabled",
+ remediation:
+ "Enable Electron observation and configure a loopback CDP endpoint and canonical file roots.",
+ };
if (kind === "session") return { reason: "available", remediation: null };
if (!targetOpen)
return {
diff --git a/src/application/ElectronEvidence.ts b/src/application/ElectronEvidence.ts
new file mode 100644
index 000000000..7bc33d683
--- /dev/null
+++ b/src/application/ElectronEvidence.ts
@@ -0,0 +1,60 @@
+import type { ProviderIdentity } from "./AnalysisProvider.js";
+import {
+ createEvidence,
+ type Evidence,
+ type EvidenceObservation,
+} from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import type {
+ ElectronPageInspection,
+ ElectronTargetList,
+ InspectElectronPageInput,
+ ListElectronTargetsInput,
+} from "../domain/electronObservation.js";
+
+type ElectronOperation = "list_electron_targets" | "inspect_electron_page";
+
+/** Create Evidence v2 for one root-confined Electron observation. */
+export const createElectronEvidence = (
+ operation: ElectronOperation,
+ input: ListElectronTargetsInput | InspectElectronPageInput,
+ result: ElectronTargetList | ElectronPageInspection,
+ provider: ProviderIdentity,
+): Evidence =>
+ createEvidence(undefined, provider, {
+ predicateType:
+ operation === "list_electron_targets"
+ ? "rea.electron-target-list/v1"
+ : "rea.electron-page-inspection/v1",
+ operation,
+ parameters: parameters(input),
+ result: jsonValueSchema.parse(result),
+ confidence: "observed",
+ authority: "external-service",
+ environment:
+ "target" in result
+ ? {
+ id: `${result.browser.product}@${result.browser.revision}`,
+ platform: process.platform,
+ architecture: process.arch,
+ isolation: "none",
+ }
+ : null,
+ limitations: result.limitations,
+ });
+
+const parameters = (
+ input: ListElectronTargetsInput | InspectElectronPageInput,
+): EvidenceObservation["parameters"] => ({
+ cdp_endpoint: input.cdp_endpoint,
+ allowed_file_roots: input.allowed_file_roots,
+ ...("target_id" in input
+ ? {
+ target_id: input.target_id,
+ observation_ms: input.observation_ms,
+ include_script_sources: input.include_script_sources,
+ source_capture_approved: input.source_capture_approved,
+ limits: input.limits,
+ }
+ : { offset: input.offset, limit: input.limit }),
+});
diff --git a/src/application/ElectronObservationPort.ts b/src/application/ElectronObservationPort.ts
new file mode 100644
index 000000000..3b882cae9
--- /dev/null
+++ b/src/application/ElectronObservationPort.ts
@@ -0,0 +1,22 @@
+import type { ExecutionOptions, ProviderIdentity } from "./AnalysisProvider.js";
+import type { AnalysisError } from "../domain/errors.js";
+import type {
+ ElectronPageInspection,
+ ElectronTargetList,
+ InspectElectronPageInput,
+ ListElectronTargetsInput,
+} from "../domain/electronObservation.js";
+import type { Result } from "../domain/result.js";
+
+/** Provider-neutral boundary for root-confined Electron file-page observation. */
+export interface ElectronObservationPort {
+ identity(): ProviderIdentity;
+ listTargets(
+ input: ListElectronTargetsInput,
+ options?: ExecutionOptions,
+ ): Promise>;
+ inspectPage(
+ input: InspectElectronPageInput,
+ options?: ExecutionOptions,
+ ): Promise>;
+}
diff --git a/src/application/ElectronObservationService.ts b/src/application/ElectronObservationService.ts
new file mode 100644
index 000000000..6b007cb0e
--- /dev/null
+++ b/src/application/ElectronObservationService.ts
@@ -0,0 +1,116 @@
+import type { ExecutionOptions } from "./AnalysisProvider.js";
+import type { ElectronObservationPort } from "./ElectronObservationPort.js";
+import type { PermissionAuthority } from "./PermissionAuthority.js";
+import type { Evidence } from "../domain/evidence.js";
+import type {
+ InspectElectronPageInput,
+ ListElectronTargetsInput,
+} from "../domain/electronObservation.js";
+import {
+ AnalysisCapabilityUnavailableError,
+ AnalysisProtocolError,
+ PermissionRequiredError,
+ type AnalysisError,
+} from "../domain/errors.js";
+import { err, ok, type Result } from "../domain/result.js";
+import { createElectronEvidence } from "./ElectronEvidence.js";
+
+/** Authorize and list root-confined Electron page targets. */
+export const listElectronTargets = async (
+ provider: ElectronObservationPort | undefined,
+ authority: PermissionAuthority | undefined,
+ input: ListElectronTargetsInput,
+ options: ExecutionOptions = {},
+): Promise> => {
+ const ready = await prepare(
+ provider,
+ authority,
+ input,
+ "list_electron_targets",
+ );
+ if (!ready.ok) return ready;
+ const result = await ready.value.listTargets(input, options);
+ return result.ok
+ ? ok(
+ createElectronEvidence(
+ "list_electron_targets",
+ input,
+ result.value,
+ ready.value.identity(),
+ ),
+ )
+ : result;
+};
+
+/** Authorize and inspect one root-confined Electron page. */
+export const inspectElectronPage = async (
+ provider: ElectronObservationPort | undefined,
+ authority: PermissionAuthority | undefined,
+ input: InspectElectronPageInput,
+ options: ExecutionOptions = {},
+): Promise> => {
+ const ready = await prepare(
+ provider,
+ authority,
+ input,
+ "inspect_electron_page",
+ );
+ if (!ready.ok) return ready;
+ const result = await ready.value.inspectPage(input, options);
+ return result.ok
+ ? ok(
+ createElectronEvidence(
+ "inspect_electron_page",
+ input,
+ result.value,
+ ready.value.identity(),
+ ),
+ )
+ : result;
+};
+
+const prepare = async (
+ provider: ElectronObservationPort | undefined,
+ authority: PermissionAuthority | undefined,
+ input: ListElectronTargetsInput | InspectElectronPageInput,
+ operation: "list_electron_targets" | "inspect_electron_page",
+): Promise> => {
+ if (authority === undefined)
+ return err(
+ new AnalysisCapabilityUnavailableError(
+ "rea-cdp-electron",
+ operation,
+ "Electron observation permission policy is not configured",
+ ),
+ );
+ const authorized = await authority.authorize(
+ {
+ capability: "electron_observe",
+ roots: input.allowed_file_roots,
+ executables: [],
+ environment_names: [],
+ origins: [input.cdp_endpoint],
+ network: "loopback",
+ mount: false,
+ operation_identity: `${operation}:${"target_id" in input ? input.target_id : input.cdp_endpoint}`,
+ },
+ "read",
+ );
+ if (!authorized.ok)
+ return err(
+ authorized.error instanceof PermissionRequiredError
+ ? authorized.error
+ : new AnalysisProtocolError(authorized.error.message, {
+ cause: authorized.error,
+ }),
+ );
+ return provider === undefined
+ ? err(
+ new AnalysisCapabilityUnavailableError(
+ "rea-cdp-electron",
+ operation,
+ "Electron observation provider is not configured",
+ ),
+ )
+ : ok(provider);
+};
diff --git a/src/application/ProjectPermissionStore.ts b/src/application/ProjectPermissionStore.ts
index 2c52c77dd..7d4d4b90a 100644
--- a/src/application/ProjectPermissionStore.ts
+++ b/src/application/ProjectPermissionStore.ts
@@ -23,6 +23,7 @@ const grantSchema = z.object({
capability: z.enum([
"process_capture",
"browser_observe",
+ "electron_observe",
"evidence_read",
"evidence_write",
"investigation_input",
diff --git a/src/browser/CdpBrowserProvider.ts b/src/browser/CdpBrowserProvider.ts
index 67914d98b..b49202f0c 100644
--- a/src/browser/CdpBrowserProvider.ts
+++ b/src/browser/CdpBrowserProvider.ts
@@ -10,10 +10,41 @@ import {
type ListBrowserTargetsInput,
type WebPageInspection,
} from "../domain/browserObservation.js";
+import { analyzeCapturedWebBundle } from "../domain/webBundleAnalyzer.js";
+import {
+ webBundleAnalysisSchema,
+ type AnalyzeWebBundleInput,
+ type WebBundleAnalysis,
+} 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 {
+ compareWebCaptures,
+ webCaptureDiffSchema,
+ type CompareWebCapturesInput,
+ type WebCaptureDiff,
+} from "../domain/webCaptureDiff.js";
+import {
+ webScreenshotDiffSchema,
+ webScreenshotSchema,
+ type CaptureWebScreenshotInput,
+ type CompareWebScreenshotsInput,
+ type WebScreenshot,
+ type WebScreenshotDiff,
+} from "../domain/webScreenshot.js";
import {
AnalysisError,
BrowserObservationError,
ProviderAdapterError,
+ type BrowserObservationOperation,
} from "../domain/errors.js";
import { err, ok, type Result } from "../domain/result.js";
import { CdpConnection } from "./CdpConnection.js";
@@ -22,12 +53,17 @@ import {
type CdpEndpointDiscovery,
type CdpEndpointTarget,
} from "./CdpEndpoint.js";
-import { capturePage } from "./CdpPageCapture.js";
+import { capturePage, type CapturedPage } from "./CdpPageCapture.js";
+import { fetchWebSourceMaps } from "./WebSourceMapFetcher.js";
+import { observeCdpSession } from "./CdpObservationSession.js";
+import { discoverWebMcp } from "./CdpWebMcpDiscovery.js";
+import { captureCdpScreenshot } from "./CdpScreenshot.js";
+import { comparePngScreenshots } from "./PngVisualDiff.js";
const IDENTITY: ProviderIdentity = {
id: "rea-cdp-browser",
name: "REA Chrome DevTools Protocol observation provider",
- version: "1",
+ version: "2",
};
/** Passive, origin-scoped browser observation through a user-owned CDP endpoint. */
@@ -81,6 +117,41 @@ export class CdpBrowserProvider implements BrowserObservationPort {
input: InspectWebPageInput,
options: ExecutionOptions = {},
): Promise> {
+ try {
+ const captured = await this.#capture(input, options);
+ return ok(webPageInspectionSchema.parse(captured.inspection));
+ } catch (cause: unknown) {
+ return err(providerError(cause, "inspect_web_page"));
+ }
+ }
+
+ async analyzeBundle(
+ input: AnalyzeWebBundleInput,
+ options: ExecutionOptions = {},
+ ): Promise> {
+ try {
+ const captured = await this.#capture(input, options);
+ const sourceMaps = input.fetch_source_maps
+ ? await fetchWebSourceMaps(
+ captured.sourceMapRequests,
+ input,
+ options.signal,
+ )
+ : undefined;
+ return ok(
+ webBundleAnalysisSchema.parse(
+ analyzeCapturedWebBundle(captured.inspection, input, sourceMaps),
+ ),
+ );
+ } catch (cause: unknown) {
+ return err(providerError(cause, "analyze_web_bundle"));
+ }
+ }
+
+ async observeSession(
+ input: ObserveWebSessionInput,
+ options: ExecutionOptions = {},
+ ): Promise> {
let connection: CdpConnection | undefined;
let sessionId: string | undefined;
try {
@@ -101,7 +172,177 @@ export class CdpBrowserProvider implements BrowserObservationPort {
options.signal,
);
sessionId = attachedSessionId(attached);
- const result = await capturePage({
+ return ok(
+ webObservationSessionSchema.parse(
+ await observeCdpSession({
+ connection,
+ sessionId,
+ discovery,
+ target,
+ input,
+ ...(options.signal === undefined ? {} : { signal: options.signal }),
+ ...(options.progress === undefined
+ ? {}
+ : { progress: options.progress }),
+ }),
+ ),
+ );
+ } catch (cause: unknown) {
+ return err(providerError(cause, "observe_web_session"));
+ } finally {
+ if (connection !== undefined) {
+ if (sessionId !== undefined)
+ await bestEffortCleanup(connection, sessionId);
+ await connection.close();
+ }
+ }
+ }
+
+ async discoverWebMcpTools(
+ input: DiscoverWebMcpToolsInput,
+ options: ExecutionOptions = {},
+ ): Promise> {
+ let connection: CdpConnection | undefined;
+ let sessionId: string | undefined;
+ try {
+ const discovery = await discoverCdpEndpoint(
+ input.cdp_endpoint,
+ "inspect_web_page",
+ options.signal,
+ );
+ const target = authorizeTarget(discovery, input);
+ connection = await CdpConnection.connect(
+ discovery.browserWebSocketUrl,
+ options.signal,
+ );
+ const attached = await connection.send(
+ "Target.attachToTarget",
+ { targetId: target.id, flatten: true },
+ undefined,
+ options.signal,
+ );
+ sessionId = attachedSessionId(attached);
+ return ok(
+ webMcpDiscoverySchema.parse(
+ await discoverWebMcp({
+ connection,
+ sessionId,
+ discovery,
+ target,
+ input,
+ ...(options.signal === undefined ? {} : { signal: options.signal }),
+ ...(options.progress === undefined
+ ? {}
+ : { progress: options.progress }),
+ }),
+ ),
+ );
+ } catch (cause: unknown) {
+ return err(providerError(cause, "discover_webmcp_tools"));
+ } finally {
+ if (connection !== undefined) {
+ if (sessionId !== undefined)
+ await bestEffortCleanup(connection, sessionId);
+ await connection.close();
+ }
+ }
+ }
+
+ async compareCaptures(
+ input: CompareWebCapturesInput,
+ ): Promise> {
+ try {
+ return ok(webCaptureDiffSchema.parse(compareWebCaptures(input)));
+ } catch (cause: unknown) {
+ return err(providerError(cause, "compare_web_captures"));
+ }
+ }
+
+ async captureScreenshot(
+ input: CaptureWebScreenshotInput,
+ options: ExecutionOptions = {},
+ ): Promise> {
+ let connection: CdpConnection | undefined;
+ let sessionId: string | undefined;
+ try {
+ const discovery = await discoverCdpEndpoint(
+ input.cdp_endpoint,
+ "inspect_web_page",
+ options.signal,
+ );
+ const target = authorizeTarget(discovery, input);
+ connection = await CdpConnection.connect(
+ discovery.browserWebSocketUrl,
+ options.signal,
+ );
+ const attached = await connection.send(
+ "Target.attachToTarget",
+ { targetId: target.id, flatten: true },
+ undefined,
+ options.signal,
+ );
+ sessionId = attachedSessionId(attached);
+ return ok(
+ webScreenshotSchema.parse(
+ await captureCdpScreenshot({
+ connection,
+ sessionId,
+ discovery,
+ target,
+ input,
+ ...(options.signal === undefined ? {} : { signal: options.signal }),
+ ...(options.progress === undefined
+ ? {}
+ : { progress: options.progress }),
+ }),
+ ),
+ );
+ } catch (cause: unknown) {
+ return err(providerError(cause, "capture_web_screenshot"));
+ } finally {
+ if (connection !== undefined) {
+ if (sessionId !== undefined)
+ await bestEffortCleanup(connection, sessionId);
+ await connection.close();
+ }
+ }
+ }
+
+ async compareScreenshots(
+ input: CompareWebScreenshotsInput,
+ ): Promise> {
+ try {
+ return ok(webScreenshotDiffSchema.parse(comparePngScreenshots(input)));
+ } catch (cause: unknown) {
+ return err(providerError(cause, "compare_web_screenshots"));
+ }
+ }
+
+ async #capture(
+ input: InspectWebPageInput,
+ options: ExecutionOptions,
+ ): Promise {
+ let connection: CdpConnection | undefined;
+ let sessionId: string | undefined;
+ try {
+ const discovery = await discoverCdpEndpoint(
+ input.cdp_endpoint,
+ "inspect_web_page",
+ options.signal,
+ );
+ const target = authorizeTarget(discovery, input);
+ connection = await CdpConnection.connect(
+ discovery.browserWebSocketUrl,
+ options.signal,
+ );
+ const attached = await connection.send(
+ "Target.attachToTarget",
+ { targetId: target.id, flatten: true },
+ undefined,
+ options.signal,
+ );
+ sessionId = attachedSessionId(attached);
+ return await capturePage({
connection,
sessionId,
discovery,
@@ -112,9 +353,6 @@ export class CdpBrowserProvider implements BrowserObservationPort {
? {}
: { progress: options.progress }),
});
- return ok(webPageInspectionSchema.parse(result));
- } catch (cause: unknown) {
- return err(providerError(cause, "inspect_web_page"));
} finally {
if (connection !== undefined) {
if (sessionId !== undefined)
@@ -172,7 +410,7 @@ const selectTargets = (
const authorizeTarget = (
discovery: CdpEndpointDiscovery,
- input: InspectWebPageInput,
+ input: Pick,
): CdpEndpointTarget => {
const target = discovery.targets.find(
(candidate) => candidate.id === input.target_id,
@@ -222,8 +460,10 @@ const bestEffortCleanup = async (
const providerError = (
cause: unknown,
- operation: "list_browser_targets" | "inspect_web_page",
+ operation: BrowserObservationOperation,
): AnalysisError =>
- cause instanceof AnalysisError
- ? cause
- : new ProviderAdapterError(IDENTITY.id, operation, { cause });
+ cause instanceof BrowserObservationError && cause.operation !== operation
+ ? new BrowserObservationError(operation, cause.reason, { cause })
+ : cause instanceof AnalysisError
+ ? cause
+ : new ProviderAdapterError(IDENTITY.id, operation, { cause });
diff --git a/src/browser/CdpCaptureCompleteness.ts b/src/browser/CdpCaptureCompleteness.ts
new file mode 100644
index 000000000..48e66e311
--- /dev/null
+++ b/src/browser/CdpCaptureCompleteness.ts
@@ -0,0 +1,119 @@
+import {
+ classifyBrowserCompleteness,
+ type BrowserCompleteness,
+ type BrowserDroppedEventKind,
+ type BrowserDroppedEvents,
+ type BrowserExclusion,
+ type BrowserExclusionReason,
+ type BrowserSection,
+} from "../domain/browserCompleteness.js";
+
+const EVENT_SECTIONS: Readonly<
+ Record
+> = {
+ scripts: "scripts",
+ network_requests: "network_requests",
+ console_events: "console_events",
+ websocket_connections: "websocket_connections",
+ websocket_frames: "websocket_frames",
+ webmcp_tools: "webmcp_tools",
+ timeline_events: "timeline",
+};
+
+const POLICY_REASONS = new Set([
+ "disallowed_origin",
+ "unsupported_url",
+ "unattributed_origin",
+ "not_approved",
+ "out_of_target_scope",
+]);
+
+/** Mutable adapter ledger projected into immutable, canonical completeness v2. */
+export class CdpCaptureCompleteness {
+ readonly #initialAttachLimited: readonly BrowserSection[];
+ readonly #policyFiltered = new Set();
+ readonly #attachLimited = new Set();
+ readonly #truncated = new Set();
+ readonly #unavailable = new Set();
+ readonly #excluded = new Map();
+ readonly #dropped: Omit = emptyDropped();
+
+ constructor(initialAttachLimited: readonly BrowserSection[] = []) {
+ this.#initialAttachLimited = [...initialAttachLimited];
+ this.reset();
+ }
+
+ reset(): void {
+ this.#policyFiltered.clear();
+ this.#attachLimited.clear();
+ this.#truncated.clear();
+ this.#unavailable.clear();
+ this.#excluded.clear();
+ Object.assign(this.#dropped, emptyDropped());
+ for (const section of this.#initialAttachLimited)
+ this.#attachLimited.add(section);
+ }
+
+ exclude(
+ section: BrowserSection,
+ reason: BrowserExclusionReason,
+ count: number | null = 1,
+ ): void {
+ if (POLICY_REASONS.has(reason)) this.#policyFiltered.add(section);
+ if (
+ reason === "provider_unavailable" ||
+ reason === "invalid_protocol_value"
+ )
+ this.#unavailable.add(section);
+ const key = `${section}\0${reason}`;
+ const existing = this.#excluded.get(key);
+ const combined =
+ count === null || existing?.count === null
+ ? null
+ : (existing?.count ?? 0) + count;
+ this.#excluded.set(key, { section, reason, count: combined });
+ }
+
+ attachLimited(section: BrowserSection): void {
+ this.#attachLimited.add(section);
+ }
+
+ unavailable(section: BrowserSection): void {
+ this.#unavailable.add(section);
+ this.exclude(section, "provider_unavailable", null);
+ }
+
+ truncate(section: BrowserSection): void {
+ this.#truncated.add(section);
+ }
+
+ drop(kind: BrowserDroppedEventKind, count = 1): void {
+ this.#dropped[kind] += count;
+ this.#truncated.add(EVENT_SECTIONS[kind]);
+ }
+
+ get droppedTotal(): number {
+ return Object.values(this.#dropped).reduce((sum, count) => sum + count, 0);
+ }
+
+ snapshot(): BrowserCompleteness {
+ return classifyBrowserCompleteness({
+ policyFilteredSections: this.#policyFiltered,
+ attachLimitedSections: this.#attachLimited,
+ truncatedSections: this.#truncated,
+ unavailableSections: this.#unavailable,
+ excluded: [...this.#excluded.values()],
+ droppedEvents: this.#dropped,
+ });
+ }
+}
+
+const emptyDropped = (): Omit => ({
+ scripts: 0,
+ network_requests: 0,
+ console_events: 0,
+ websocket_connections: 0,
+ websocket_frames: 0,
+ webmcp_tools: 0,
+ timeline_events: 0,
+});
diff --git a/src/browser/CdpCaptureDocuments.ts b/src/browser/CdpCaptureDocuments.ts
index b716dbf17..5f7173f74 100644
--- a/src/browser/CdpCaptureDocuments.ts
+++ b/src/browser/CdpCaptureDocuments.ts
@@ -5,6 +5,7 @@ import type {
import {
allowedSanitizedUrl,
boundedText,
+ isHttpUrl,
numberValue,
recordValue,
recordsValue,
@@ -12,12 +13,19 @@ import {
stringValue,
type UnknownRecord,
} from "./CdpCaptureValues.js";
+import type { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
+
+export type CapturedResource = Omit<
+ WebPageInspection["resources"][number],
+ "resource_key"
+> & { readonly rawUrl: string };
/** Normalize allowed frames while retaining a bounded prefix and total count. */
export const captureFrames = (
result: unknown,
allowedOrigins: ReadonlySet,
maximum: number,
+ completeness?: CdpCaptureCompleteness,
): {
readonly total: number;
readonly items: WebPageInspection["frames"];
@@ -30,14 +38,17 @@ export const captureFrames = (
const frame = recordValue(tree.frame);
const frameId = stringValue(frame?.id);
const sanitized = allowedSanitizedUrl(frame?.url, allowedOrigins);
- if (
- frame === undefined ||
- frameId === undefined ||
- frameId.length > 256 ||
- sanitized === undefined ||
- sanitized.origin === null
- )
+ if (frame === undefined || frameId === undefined || frameId.length > 256) {
+ completeness?.exclude("frames", "invalid_protocol_value");
continue;
+ }
+ if (sanitized === undefined || sanitized.origin === null) {
+ completeness?.exclude(
+ "frames",
+ exclusionReasonForUrl(stringValue(frame.url)),
+ );
+ continue;
+ }
total += 1;
if (items.length >= maximum) continue;
items.push({
@@ -62,22 +73,30 @@ export const captureResources = (
result: unknown,
allowedOrigins: ReadonlySet,
maximum: number,
+ completeness?: CdpCaptureCompleteness,
): {
readonly total: number;
- readonly items: WebPageInspection["resources"];
+ readonly items: readonly CapturedResource[];
} => {
const root = recordValue(requiredRecord(result).frameTree);
if (root === undefined) return { total: 0, items: [] };
- const items: WebPageInspection["resources"] = [];
+ const items: CapturedResource[] = [];
let total = 0;
for (const tree of walkFrameTrees(root)) {
for (const resource of recordsValue(tree.resources)) {
const url = allowedSanitizedUrl(resource.url, allowedOrigins);
- if (url === undefined || url.origin === null) continue;
+ if (url === undefined || url.origin === null) {
+ completeness?.exclude(
+ "resources",
+ exclusionReasonForUrl(stringValue(resource.url)),
+ );
+ continue;
+ }
total += 1;
if (items.length >= maximum) continue;
const contentSize = numberValue(resource.contentSize);
items.push({
+ rawUrl: stringValue(resource.url) ?? "",
url: url.url,
origin: url.origin,
type: (stringValue(resource.type) ?? "Other").slice(0, 100),
@@ -110,20 +129,29 @@ export const captureDom = (
result: unknown,
allowedOrigins: ReadonlySet,
input: InspectWebPageInput,
+ completeness?: CdpCaptureCompleteness,
): {
readonly total: number;
readonly nodes: WebPageInspection["dom"]["nodes"];
+ readonly urls: WebPageInspection["metadata"]["dom_urls"];
+ readonly agentHints: WebPageInspection["metadata"]["agent_hints"];
+ readonly excludedUrls: number;
} => {
const root = requiredRecord(result);
const strings = Array.isArray(root.strings)
? root.strings.map((value) => stringValue(value) ?? "")
: [];
const nodes: WebPageInspection["dom"]["nodes"] = [];
+ const urls: WebPageInspection["metadata"]["dom_urls"] = [];
+ const agentHints: WebPageInspection["metadata"]["agent_hints"] = [];
+ let excludedUrls = 0;
let total = 0;
for (const document of recordsValue(root.documents)) {
const documentUrl = indexedString(strings, document.documentURL);
- if (allowedSanitizedUrl(documentUrl, allowedOrigins) === undefined)
+ if (allowedSanitizedUrl(documentUrl, allowedOrigins) === undefined) {
+ completeness?.exclude("dom", exclusionReasonForUrl(documentUrl));
continue;
+ }
const documentNodes = recordValue(document.nodes);
if (documentNodes === undefined) continue;
const nodeTypes = numberArray(documentNodes.nodeType);
@@ -142,42 +170,129 @@ export const captureDom = (
) {
const attributeIndexes = numberArray(attributes[index]);
const parent = Math.trunc(parents[index] ?? -1);
+ const nodeIndex = nodes.length;
+ const nodeName = indexedString(strings, nodeNames[index]).slice(0, 256);
nodes.push({
- index: nodes.length,
+ index: nodeIndex,
parent_index: parent < 0 ? -1 : baseIndex + parent,
node_type: Math.max(0, Math.trunc(nodeTypes[index] ?? 0)),
- node_name: indexedString(strings, nodeNames[index]).slice(0, 256),
+ node_name: nodeName,
node_value_length: indexedString(strings, nodeValues[index]).length,
attribute_names: attributeIndexes
.filter((_value, attributeIndex) => attributeIndex % 2 === 0)
.map((value) => indexedString(strings, value).slice(0, 256))
.slice(0, 200),
});
+ const metadata = domMetadata(
+ strings,
+ attributeIndexes,
+ documentUrl,
+ nodeIndex,
+ nodeName,
+ allowedOrigins,
+ );
+ for (const url of metadata.urls) {
+ if (urls.length >= input.limits.max_resources) {
+ completeness?.truncate("metadata");
+ continue;
+ }
+ urls.push(url);
+ if (url.destination_scope !== "approved") {
+ excludedUrls += 1;
+ completeness?.exclude(
+ "metadata",
+ url.destination_scope === "outside_policy"
+ ? "disallowed_origin"
+ : "unsupported_url",
+ );
+ }
+ }
+ agentHints.push(...metadata.agentHints);
}
}
- return { total, nodes };
+ return {
+ total,
+ nodes,
+ urls,
+ agentHints: agentHints.slice(0, input.limits.max_resources),
+ excludedUrls,
+ };
};
export const captureAccessibility = (
results: readonly unknown[],
maximum: number,
+ options: {
+ readonly includeText: boolean;
+ readonly maximumFieldBytes: number;
+ readonly maximumTotalBytes: number;
+ readonly unavailable?: boolean;
+ },
): {
readonly total: number;
readonly nodes: WebPageInspection["accessibility"]["nodes"];
+ readonly textCapture: WebPageInspection["accessibility"]["text_capture"];
} => {
const all = results.flatMap((result) =>
recordsValue(requiredRecord(result).nodes),
);
- return {
- total: all.length,
- nodes: all.slice(0, maximum).map((node) => ({
+ let retainedBytes = 0;
+ let excludedFields = 0;
+ let truncatedFields = 0;
+ const nodes = all.slice(0, maximum).map((node) => {
+ const captureText = (value: unknown): string | null => {
+ const raw = stringValue(recordValue(value)?.value);
+ if (raw === undefined) return null;
+ if (!options.includeText) {
+ excludedFields += 1;
+ return null;
+ }
+ const available = Math.max(0, options.maximumTotalBytes - retainedBytes);
+ const captured = boundedUtf8(
+ raw,
+ Math.min(options.maximumFieldBytes, available),
+ );
+ retainedBytes += captured.bytes;
+ if (captured.truncated) {
+ truncatedFields += 1;
+ if (captured.text === "" && raw !== "") {
+ excludedFields += 1;
+ return null;
+ }
+ }
+ return captured.text;
+ };
+ return {
node_id: (stringValue(node.nodeId) ?? "").slice(0, 256),
parent_id: (stringValue(node.parentId) ?? "").slice(0, 256) || null,
role: axText(node.role),
- name: axText(node.name),
- description: axText(node.description),
+ name: captureText(node.name),
+ description: captureText(node.description),
ignored: node.ignored === true,
- })),
+ };
+ });
+ for (const node of all.slice(maximum)) {
+ for (const value of [node.name, node.description]) {
+ if (stringValue(recordValue(value)?.value) === undefined) continue;
+ excludedFields += 1;
+ if (options.includeText) truncatedFields += 1;
+ }
+ }
+ return {
+ total: all.length,
+ nodes,
+ textCapture: {
+ status: options.unavailable
+ ? "unavailable"
+ : !options.includeText
+ ? "not_approved"
+ : truncatedFields > 0
+ ? "truncated"
+ : "included",
+ retained_bytes: retainedBytes,
+ excluded_fields: excludedFields,
+ truncated_fields: truncatedFields,
+ },
};
};
@@ -196,3 +311,112 @@ const numberArray = (value: unknown): readonly number[] =>
return number === undefined ? [] : [number];
})
: [];
+
+const domMetadata = (
+ strings: readonly string[],
+ attributes: readonly number[],
+ documentUrl: string,
+ nodeIndex: number,
+ nodeName: string,
+ allowedOrigins: ReadonlySet,
+): {
+ readonly urls: WebPageInspection["metadata"]["dom_urls"];
+ readonly agentHints: WebPageInspection["metadata"]["agent_hints"];
+} => {
+ const pairs = new Map();
+ for (let index = 0; index + 1 < attributes.length; index += 2) {
+ const name = indexedString(strings, attributes[index]).toLowerCase();
+ const value = indexedString(strings, attributes[index + 1]);
+ pairs.set(name, value);
+ }
+ const urls: WebPageInspection["metadata"]["dom_urls"] = [];
+ for (const attribute of domUrlAttributes) {
+ const value = pairs.get(attribute);
+ if (value === undefined) continue;
+ const destination = domDestination(value, documentUrl, allowedOrigins);
+ urls.push({
+ node_index: nodeIndex,
+ attribute,
+ url: destination.url,
+ destination_scope: destination.scope,
+ });
+ }
+ const rel = (pairs.get("rel") ?? "")
+ .toLowerCase()
+ .split(/\s+/u)
+ .filter((value) => agentRelValues.includes(value));
+ const href = urls.find(({ attribute }) => attribute === "href")?.url ?? null;
+ const agentHints =
+ nodeName.toLowerCase() === "link" && rel.length > 0
+ ? rel.map((declaration) => ({
+ mechanism: "dom_link_rel" as const,
+ declaration,
+ url: href,
+ trust: "page-declared-untrusted" as const,
+ }))
+ : [];
+ return { urls, agentHints };
+};
+
+const domDestination = (
+ value: string,
+ documentUrl: string,
+ allowedOrigins: ReadonlySet,
+): {
+ readonly url: string | null;
+ readonly scope: "approved" | "outside_policy" | "unsupported";
+} => {
+ try {
+ const parsed = new URL(value, documentUrl);
+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+ return { url: null, scope: "unsupported" };
+ if (!allowedOrigins.has(parsed.origin))
+ return { url: null, scope: "outside_policy" };
+ return {
+ url: allowedSanitizedUrl(parsed.href, allowedOrigins)?.url ?? null,
+ scope: "approved",
+ };
+ } catch {
+ return { url: null, scope: "unsupported" };
+ }
+};
+
+const boundedUtf8 = (
+ value: string,
+ maximumBytes: number,
+): {
+ readonly text: string;
+ readonly bytes: number;
+ readonly truncated: boolean;
+} => {
+ const total = Buffer.byteLength(value);
+ if (total <= maximumBytes)
+ return { text: value, bytes: total, truncated: false };
+ let text = "";
+ let bytes = 0;
+ for (const character of value) {
+ const characterBytes = Buffer.byteLength(character);
+ if (bytes + characterBytes > maximumBytes) break;
+ text += character;
+ bytes += characterBytes;
+ }
+ return { text, bytes, truncated: true };
+};
+
+const exclusionReasonForUrl = (
+ value: string | undefined,
+): "disallowed_origin" | "unsupported_url" | "unattributed_origin" =>
+ value === undefined || value === ""
+ ? "unattributed_origin"
+ : isHttpUrl(value)
+ ? "disallowed_origin"
+ : "unsupported_url";
+
+const domUrlAttributes = [
+ "href",
+ "src",
+ "action",
+ "formaction",
+ "poster",
+] as const;
+const agentRelValues = ["mcp", "model-context", "ai-plugin", "service-desc"];
diff --git a/src/browser/CdpCaptureEvents.ts b/src/browser/CdpCaptureEvents.ts
index 2a254af03..67e45974f 100644
--- a/src/browser/CdpCaptureEvents.ts
+++ b/src/browser/CdpCaptureEvents.ts
@@ -2,7 +2,11 @@ import type {
InspectWebPageInput,
WebPageInspection,
} from "../domain/browserObservation.js";
+import { inferJsonShape, type JsonShape } from "../domain/jsonShape.js";
import type { CdpEvent } from "./CdpConnection.js";
+import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
+import { safeResponseMetadata } from "./CdpSafeMetadata.js";
+import { boundedSensitiveText } from "./SensitiveTextCapture.js";
import {
allowedSanitizedUrl,
boundedText,
@@ -16,6 +20,7 @@ import {
export interface CapturedScript {
readonly scriptId: string;
+ readonly rawUrl: string;
readonly url: string;
readonly origin: string | null;
readonly hash: string;
@@ -23,6 +28,7 @@ export interface CapturedScript {
readonly isModule: boolean;
readonly language: string | null;
readonly sourceMapUrl: string | null;
+ readonly sourceMapRawUrl: string | null;
}
type NetworkState = WebPageInspection["network"]["requests"][number];
@@ -34,10 +40,21 @@ export class CdpCaptureEvents {
readonly allowedWebSockets = new Set();
readonly console: WebPageInspection["console"]["events"] = [];
readonly websockets: WebPageInspection["network"]["websocket_events"] = [];
- dropped = 0;
+ readonly responseMetadata: WebPageInspection["metadata"]["responses"] = [];
+ readonly agentHints: WebPageInspection["metadata"]["agent_hints"] = [];
+ readonly completeness = new CdpCaptureCompleteness([
+ "network_requests",
+ "console_events",
+ "websocket_connections",
+ "websocket_frames",
+ "metadata",
+ ]);
originViolation = false;
navigationDuringCapture = false;
#mainFrameId: string | undefined;
+ #consoleTextBytes = 0;
+ #jsonBodyBytes = 0;
+ #websocketShapeBytes = 0;
constructor(
private readonly input: InspectWebPageInput,
@@ -48,12 +65,23 @@ export class CdpCaptureEvents {
this.#mainFrameId = frameId;
this.originViolation = false;
this.navigationDuringCapture = false;
- this.dropped = 0;
this.scripts.clear();
this.network.clear();
this.allowedWebSockets.clear();
this.console.length = 0;
this.websockets.length = 0;
+ this.responseMetadata.length = 0;
+ this.agentHints.length = 0;
+ this.#consoleTextBytes = 0;
+ this.#jsonBodyBytes = 0;
+ this.#websocketShapeBytes = 0;
+ this.completeness.reset();
+ if (!this.input.include_console_text)
+ this.completeness.exclude("console_text", "not_approved", null);
+ if (!this.input.include_json_body_shapes)
+ this.completeness.exclude("json_body_shapes", "not_approved", null);
+ if (!this.input.include_websocket_shapes)
+ this.completeness.exclude("websocket_shapes", "not_approved", null);
}
beginFinalCapture(frameId: string): void {
@@ -99,21 +127,25 @@ export class CdpCaptureEvents {
const scriptId = stringValue(params.scriptId);
const rawUrl = stringValue(params.url) ?? "";
const sanitized = allowedSanitizedUrl(rawUrl, this.allowedOrigins);
- if (
- scriptId === undefined ||
- scriptId.length > 256 ||
- sanitized === undefined
- )
+ if (scriptId === undefined || scriptId.length > 256) {
+ this.completeness.exclude("scripts", "invalid_protocol_value");
return;
+ }
+ if (sanitized === undefined) {
+ this.completeness.exclude("scripts", exclusionReasonForUrl(rawUrl));
+ return;
+ }
if (
this.scripts.size >= this.input.limits.max_scripts &&
!this.scripts.has(scriptId)
) {
- this.dropped += 1;
+ this.completeness.drop("scripts");
return;
}
+ const sourceMap = this.#sourceMap(params.sourceMapURL);
this.scripts.set(scriptId, {
scriptId,
+ rawUrl,
url: sanitized.url,
origin: sanitized.origin,
hash: (stringValue(params.hash) ?? "").slice(0, 512),
@@ -126,21 +158,43 @@ export class CdpCaptureEvents {
),
isModule: params.isModule === true,
language: boundedText(params.scriptLanguage, 100),
- sourceMapUrl: this.#sourceMap(params.sourceMapURL),
+ sourceMapUrl: sourceMap.sanitized,
+ sourceMapRawUrl: sourceMap.raw,
});
}
- #sourceMap(value: unknown): string | null {
- const sanitized = allowedSanitizedUrl(value, this.allowedOrigins);
- return sanitized?.url ?? null;
+ #sourceMap(value: unknown): {
+ readonly sanitized: string | null;
+ readonly raw: string | null;
+ } {
+ const rawUrl = stringValue(value);
+ if (rawUrl === undefined || rawUrl === "")
+ return { sanitized: null, raw: null };
+ const sanitized = allowedSanitizedUrl(rawUrl, this.allowedOrigins);
+ if (sanitized !== undefined)
+ return { sanitized: sanitized.url, raw: rawUrl };
+ this.completeness.exclude("source_maps", exclusionReasonForUrl(rawUrl));
+ return { sanitized: null, raw: null };
}
#request(params: UnknownRecord): void {
const requestId = stringValue(params.requestId);
const request = recordValue(params.request);
- const sanitized = allowedSanitizedUrl(request?.url, this.allowedOrigins);
- if (requestId === undefined || requestId.length > 256) return;
- if (request === undefined || sanitized === undefined) {
+ if (requestId === undefined || requestId.length > 256) {
+ this.completeness.exclude("network_requests", "invalid_protocol_value");
+ return;
+ }
+ if (request === undefined) {
+ this.completeness.exclude("network_requests", "invalid_protocol_value");
+ this.network.delete(requestId);
+ return;
+ }
+ const sanitized = allowedSanitizedUrl(request.url, this.allowedOrigins);
+ if (sanitized === undefined) {
+ this.completeness.exclude(
+ "network_requests",
+ exclusionReasonForUrl(stringValue(request.url)),
+ );
this.network.delete(requestId);
return;
}
@@ -148,14 +202,21 @@ export class CdpCaptureEvents {
this.network.size >= this.input.limits.max_network_events &&
!this.network.has(requestId)
) {
- this.dropped += 1;
+ this.completeness.drop("network_requests");
return;
}
const initiator = recordValue(params.initiator);
+ const initiatorFrame = initiatorLocation(initiator);
+ const rawInitiatorUrl = stringValue(initiatorFrame?.url);
const initiatorUrl = allowedSanitizedUrl(
- firstCallFrame(initiator)?.url,
+ rawInitiatorUrl,
this.allowedOrigins,
);
+ if (rawInitiatorUrl !== undefined && initiatorUrl === undefined)
+ this.completeness.exclude(
+ "network_initiators",
+ exclusionReasonForUrl(rawInitiatorUrl),
+ );
this.network.set(requestId, {
request_id: requestId,
url: sanitized.url,
@@ -168,20 +229,30 @@ export class CdpCaptureEvents {
initiator: {
type: (stringValue(initiator?.type) ?? "other").slice(0, 100),
url: initiatorUrl?.url ?? null,
- line: integerOrNull(firstCallFrame(initiator)?.lineNumber),
- column: integerOrNull(firstCallFrame(initiator)?.columnNumber),
+ line: integerOrNull(initiatorFrame?.lineNumber),
+ column: integerOrNull(initiatorFrame?.columnNumber),
},
+ body_shapes: this.#requestBodyShape(request),
});
}
#response(params: UnknownRecord): void {
const requestId = stringValue(params.requestId);
- if (requestId === undefined || requestId.length > 256) return;
+ if (requestId === undefined || requestId.length > 256) {
+ this.completeness.exclude("network_requests", "invalid_protocol_value");
+ return;
+ }
const current = this.network.get(requestId);
const response = recordValue(params.response);
- const sanitized = allowedSanitizedUrl(response?.url, this.allowedOrigins);
if (current === undefined) return;
+ const sanitized = allowedSanitizedUrl(response?.url, this.allowedOrigins);
if (response === undefined || sanitized === undefined) {
+ this.completeness.exclude(
+ "network_requests",
+ response === undefined
+ ? "invalid_protocol_value"
+ : exclusionReasonForUrl(stringValue(response.url)),
+ );
this.network.delete(requestId);
return;
}
@@ -190,6 +261,18 @@ export class CdpCaptureEvents {
status: numberValue(response.status) ?? null,
mime_type: boundedText(response.mimeType, 256),
});
+ if (this.responseMetadata.length >= this.input.limits.max_network_events) {
+ this.completeness.truncate("metadata");
+ return;
+ }
+ const metadata = safeResponseMetadata(
+ requestId,
+ sanitized.url,
+ response,
+ this.allowedOrigins,
+ );
+ this.responseMetadata.push(metadata.response);
+ this.agentHints.push(...metadata.agentHints);
}
#finished(params: UnknownRecord): void {
@@ -208,23 +291,35 @@ export class CdpCaptureEvents {
#console(params: UnknownRecord): void {
const frame = firstCallFrame(recordValue(params.stackTrace));
- const source = allowedSanitizedUrl(frame?.url, this.allowedOrigins);
- if (frame === undefined || source === undefined) return;
- if (this.console.length >= this.input.limits.max_console_events) {
- this.dropped += 1;
+ if (frame === undefined) {
+ this.completeness.exclude("console_events", "unattributed_origin");
return;
}
+ const source = allowedSanitizedUrl(frame.url, this.allowedOrigins);
+ if (source === undefined) {
+ this.completeness.exclude(
+ "console_events",
+ exclusionReasonForUrl(stringValue(frame.url)),
+ );
+ return;
+ }
+ if (this.console.length >= this.input.limits.max_console_events) {
+ this.completeness.drop("console_events");
+ return;
+ }
+ const arguments_ = recordsValue(params.args);
this.console.push({
type: (stringValue(params.type) ?? "unknown").slice(0, 100),
timestamp: numberValue(params.timestamp) ?? 0,
- argument_types: recordsValue(params.args)
+ argument_types: arguments_
.map((argument) =>
(stringValue(argument.type) ?? "unknown").slice(0, 100),
)
.slice(0, 100),
- url: source?.url ?? null,
- line: integerOrNull(frame?.lineNumber),
- column: integerOrNull(frame?.columnNumber),
+ url: source.url,
+ line: integerOrNull(frame.lineNumber),
+ column: integerOrNull(frame.columnNumber),
+ text_capture: this.#consoleText(arguments_),
});
}
@@ -237,48 +332,243 @@ export class CdpCaptureEvents {
)
return;
if (this.websockets.length >= this.input.limits.max_websocket_events) {
- this.dropped += 1;
+ this.completeness.drop("websocket_frames");
return;
}
const response = recordValue(params.response);
const payload = stringValue(response?.payloadData) ?? "";
const opcode = Math.max(0, Math.trunc(numberValue(response?.opcode) ?? 0));
+ const decoded = opcode === 1 ? undefined : decodeBase64(payload);
+ if (opcode !== 1 && decoded === undefined)
+ this.completeness.exclude("websocket_frames", "invalid_protocol_value");
this.websockets.push({
request_id: requestId,
direction,
opcode,
payload_bytes:
- opcode === 1
- ? Buffer.byteLength(payload)
- : Buffer.from(payload, "base64").byteLength,
+ opcode === 1 ? Buffer.byteLength(payload) : (decoded?.byteLength ?? 0),
+ payload_shape: this.#websocketShape(payload, opcode),
});
}
+ responseBodyRequestIds(): readonly string[] {
+ if (!this.input.include_json_body_shapes) return [];
+ return [...this.network.values()]
+ .filter((request) => isJsonMediaType(request.mime_type))
+ .map((request) => request.request_id);
+ }
+
+ responseBodyUnavailable(requestId: string): void {
+ this.#updateResponseShape(requestId, null, false);
+ this.completeness.unavailable("json_body_shapes");
+ }
+
+ ingestResponseBody(requestId: string, value: unknown): void {
+ const result = recordValue(value);
+ const body = stringValue(result?.body);
+ if (body === undefined) {
+ this.#invalidResponseBody(requestId);
+ return;
+ }
+ const decoded =
+ result?.base64Encoded === true
+ ? decodeBase64(body)?.toString("utf8")
+ : body;
+ if (decoded === undefined) {
+ this.#invalidResponseBody(requestId);
+ return;
+ }
+ const inferred = this.#inferBodyShape(decoded);
+ this.#updateResponseShape(requestId, inferred.shape, inferred.truncated);
+ }
+
+ #invalidResponseBody(requestId: string): void {
+ this.#updateResponseShape(requestId, null, false);
+ this.completeness.exclude("json_body_shapes", "invalid_protocol_value");
+ }
+
+ #requestBodyShape(request: UnknownRecord): NetworkState["body_shapes"] {
+ if (!this.input.include_json_body_shapes)
+ return { status: "not_approved", request: null, response: null };
+ const body = stringValue(request.postData);
+ if (!isJsonContentType(recordValue(request.headers)) || body === undefined)
+ return { status: "unavailable", request: null, response: null };
+ const inferred = this.#inferBodyShape(body);
+ return {
+ status: inferred.truncated
+ ? "truncated"
+ : inferred.shape === null
+ ? "unavailable"
+ : "included",
+ request: inferred.shape,
+ response: null,
+ };
+ }
+
+ #inferBodyShape(text: string): {
+ readonly shape: JsonShape | null;
+ readonly truncated: boolean;
+ } {
+ const bytes = Buffer.byteLength(text);
+ const remaining =
+ this.input.limits.max_total_json_body_bytes - this.#jsonBodyBytes;
+ if (bytes > this.input.limits.max_json_body_bytes || bytes > remaining) {
+ this.completeness.truncate("json_body_shapes");
+ return { shape: null, truncated: true };
+ }
+ this.#jsonBodyBytes += bytes;
+ const shape = inferJsonShape(text, {
+ maximumBytes: this.input.limits.max_json_body_bytes,
+ maximumNodes: this.input.limits.max_json_shape_nodes,
+ maximumDepth: this.input.limits.max_json_shape_depth,
+ });
+ if (shape?.truncated === true)
+ this.completeness.truncate("json_body_shapes");
+ return { shape, truncated: shape?.truncated === true };
+ }
+
+ #updateResponseShape(
+ requestId: string,
+ response: JsonShape | null,
+ truncated: boolean,
+ ): void {
+ const current = this.network.get(requestId);
+ if (current === undefined) return;
+ const request = current.body_shapes.request;
+ const status =
+ truncated || current.body_shapes.status === "truncated"
+ ? "truncated"
+ : response !== null
+ ? "included"
+ : request !== null
+ ? "partial"
+ : "unavailable";
+ this.network.set(requestId, {
+ ...current,
+ body_shapes: { status, request, response },
+ });
+ }
+
+ #consoleText(
+ arguments_: readonly UnknownRecord[],
+ ): WebPageInspection["console"]["events"][number]["text_capture"] {
+ if (!this.input.include_console_text)
+ return {
+ status: "not_approved",
+ values: [],
+ retained_bytes: 0,
+ truncated_values: 0,
+ };
+ const values: WebPageInspection["console"]["events"][number]["text_capture"]["values"] =
+ [];
+ let retainedBytes = 0;
+ let truncatedValues = 0;
+ for (const [argumentIndex, argument] of arguments_.entries()) {
+ const primitive = consolePrimitive(argument);
+ if (primitive === undefined) continue;
+ const remaining =
+ this.input.limits.max_total_console_text_bytes - this.#consoleTextBytes;
+ if (remaining <= 0) {
+ truncatedValues += 1;
+ continue;
+ }
+ const bounded = boundedSensitiveText(
+ primitive.text,
+ Math.min(this.input.limits.max_console_text_field_bytes, remaining),
+ );
+ values.push({
+ argument_index: argumentIndex,
+ type: primitive.type,
+ text: bounded.text,
+ });
+ retainedBytes += bounded.bytes;
+ this.#consoleTextBytes += bounded.bytes;
+ if (bounded.truncated) truncatedValues += 1;
+ }
+ if (truncatedValues > 0) this.completeness.truncate("console_text");
+ return {
+ status: truncatedValues > 0 ? "truncated" : "included",
+ values,
+ retained_bytes: retainedBytes,
+ truncated_values: truncatedValues,
+ };
+ }
+
+ #websocketShape(
+ payload: string,
+ opcode: number,
+ ): WebPageInspection["network"]["websocket_events"][number]["payload_shape"] {
+ if (!this.input.include_websocket_shapes) return null;
+ if (opcode !== 1)
+ return { format: "binary", json_shape: null, truncated: false };
+ const bytes = Buffer.byteLength(payload);
+ const remaining =
+ this.input.limits.max_total_websocket_shape_bytes -
+ this.#websocketShapeBytes;
+ if (
+ bytes > this.input.limits.max_websocket_shape_bytes ||
+ bytes > remaining
+ ) {
+ this.completeness.truncate("websocket_shapes");
+ return { format: "text", json_shape: null, truncated: true };
+ }
+ this.#websocketShapeBytes += bytes;
+ const shape = inferJsonShape(payload, {
+ maximumBytes: this.input.limits.max_websocket_shape_bytes,
+ maximumNodes: this.input.limits.max_json_shape_nodes,
+ maximumDepth: this.input.limits.max_json_shape_depth,
+ });
+ if (shape?.truncated === true)
+ this.completeness.truncate("websocket_shapes");
+ return {
+ format: shape === null ? "text" : "json",
+ json_shape: shape,
+ truncated: shape?.truncated === true,
+ };
+ }
+
#websocketCreated(params: UnknownRecord): void {
const requestId = stringValue(params.requestId);
const rawUrl = stringValue(params.url);
- if (
- requestId === undefined ||
- requestId.length > 256 ||
- rawUrl === undefined
- )
+ if (requestId === undefined || requestId.length > 256) {
+ this.completeness.exclude(
+ "websocket_connections",
+ "invalid_protocol_value",
+ );
return;
+ }
+ if (rawUrl === undefined) {
+ this.completeness.exclude(
+ "websocket_connections",
+ "invalid_protocol_value",
+ );
+ return;
+ }
let parsed: URL;
try {
parsed = new URL(rawUrl);
} catch {
+ this.completeness.exclude("websocket_connections", "unsupported_url");
return;
}
if (parsed.protocol === "ws:") parsed.protocol = "http:";
else if (parsed.protocol === "wss:") parsed.protocol = "https:";
- else return;
+ else {
+ this.completeness.exclude("websocket_connections", "unsupported_url");
+ return;
+ }
+ if (!this.allowedOrigins.has(parsed.origin)) {
+ this.completeness.exclude("websocket_connections", "disallowed_origin");
+ return;
+ }
if (
- this.allowedOrigins.has(parsed.origin) &&
- (this.allowedWebSockets.has(requestId) ||
- this.allowedWebSockets.size < this.input.limits.max_websocket_events)
- )
- this.allowedWebSockets.add(requestId);
- else if (this.allowedOrigins.has(parsed.origin)) this.dropped += 1;
+ !this.allowedWebSockets.has(requestId) &&
+ this.allowedWebSockets.size >= this.input.limits.max_websocket_events
+ ) {
+ this.completeness.drop("websocket_connections");
+ return;
+ }
+ this.allowedWebSockets.add(requestId);
}
#frameNavigated(params: UnknownRecord): void {
@@ -296,12 +586,85 @@ export class CdpCaptureEvents {
const firstCallFrame = (
value: UnknownRecord | undefined,
+): UnknownRecord | undefined => recordsValue(value?.callFrames)[0];
+
+const initiatorLocation = (
+ initiator: UnknownRecord | undefined,
): UnknownRecord | undefined => {
- const callFrames = recordsValue(value?.callFrames);
- return callFrames[0];
+ let stack = recordValue(initiator?.stack);
+ for (let depth = 0; depth < 32 && stack !== undefined; depth += 1) {
+ const frame = firstCallFrame(stack);
+ if (frame !== undefined) return frame;
+ stack = recordValue(stack.parent);
+ }
+ return stringValue(initiator?.url) === undefined ? undefined : initiator;
};
+const exclusionReasonForUrl = (
+ value: string | undefined,
+): "disallowed_origin" | "unsupported_url" | "unattributed_origin" =>
+ value === undefined || value === ""
+ ? "unattributed_origin"
+ : isHttpUrl(value)
+ ? "disallowed_origin"
+ : "unsupported_url";
+
const integerOrNull = (value: unknown): number | null => {
const number = numberValue(value);
return number === undefined ? null : Math.max(0, Math.trunc(number));
};
+
+const isJsonContentType = (headers: UnknownRecord | undefined): boolean => {
+ if (headers === undefined) return false;
+ for (const [name, value] of Object.entries(headers))
+ if (
+ name.toLowerCase() === "content-type" &&
+ isJsonMediaType(stringValue(value))
+ )
+ return true;
+ return false;
+};
+
+const isJsonMediaType = (value: string | null | undefined): boolean => {
+ const mediaType = value?.split(";", 1)[0]?.trim().toLowerCase();
+ return (
+ mediaType === "application/json" || mediaType?.endsWith("+json") === true
+ );
+};
+
+const consolePrimitive = (
+ value: UnknownRecord,
+): { readonly type: string; readonly text: string } | undefined => {
+ const type = stringValue(value.type);
+ switch (type) {
+ case "string":
+ return typeof value.value === "string"
+ ? { type, text: value.value }
+ : undefined;
+ case "boolean":
+ return typeof value.value === "boolean"
+ ? { type, text: String(value.value) }
+ : undefined;
+ case "number":
+ return typeof value.value === "number"
+ ? { type, text: String(value.value) }
+ : typeof value.unserializableValue === "string"
+ ? { type, text: value.unserializableValue }
+ : undefined;
+ case "bigint":
+ return typeof value.unserializableValue === "string"
+ ? { type, text: value.unserializableValue }
+ : undefined;
+ case "undefined":
+ return { type, text: "undefined" };
+ default:
+ return undefined;
+ }
+};
+
+const BASE64 = /^(?:[A-Za-z\d+/]{4})*(?:[A-Za-z\d+/]{2}==|[A-Za-z\d+/]{3}=)?$/u;
+
+const decodeBase64 = (value: string): Buffer | undefined =>
+ value.length % 4 === 0 && BASE64.test(value)
+ ? Buffer.from(value, "base64")
+ : undefined;
diff --git a/src/browser/CdpCaptureValues.ts b/src/browser/CdpCaptureValues.ts
index 439786cff..ffa601fc8 100644
--- a/src/browser/CdpCaptureValues.ts
+++ b/src/browser/CdpCaptureValues.ts
@@ -1,10 +1,9 @@
-import { createHash } from "node:crypto";
-
import {
AnalysisCancelledError,
BrowserObservationError,
} from "../domain/errors.js";
import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
+import { createWebTextArtifact } from "../domain/webContentArtifact.js";
export type UnknownRecord = Readonly>;
@@ -64,11 +63,9 @@ export const allowedSanitizedUrl = (
export const sourceResult = (
source: string,
-): { included: true; sha256: string; bytes: number; content: string } => ({
+): { included: true; artifact: ReturnType } => ({
included: true,
- sha256: createHash("sha256").update(source).digest("hex"),
- bytes: Buffer.byteLength(source),
- content: source,
+ artifact: createWebTextArtifact(source, "text/javascript"),
});
export const sourceExcluded = (
diff --git a/src/browser/CdpElectronInspection.ts b/src/browser/CdpElectronInspection.ts
new file mode 100644
index 000000000..9aa0e7172
--- /dev/null
+++ b/src/browser/CdpElectronInspection.ts
@@ -0,0 +1,481 @@
+import { createHash } from "node:crypto";
+
+import canonicalize from "canonicalize";
+
+import type { ProgressReporter } from "../application/ProgressReporter.js";
+import type {
+ ElectronPageInspection,
+ InspectElectronPageInput,
+} from "../domain/electronObservation.js";
+import { BrowserObservationError } from "../domain/errors.js";
+import { createWebTextArtifact } from "../domain/webContentArtifact.js";
+import type { CdpConnection, CdpEvent } from "./CdpConnection.js";
+import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js";
+import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
+import {
+ boundedText,
+ delayWithCancellation,
+ numberValue,
+ recordValue,
+ recordsValue,
+ requiredRecord,
+ stringValue,
+ type UnknownRecord,
+} from "./CdpCaptureValues.js";
+import {
+ authorizedElectronFile,
+ canonicalElectronRoots,
+} from "./ElectronFileScope.js";
+
+interface ElectronContext {
+ readonly connection: CdpConnection;
+ readonly sessionId: string;
+ readonly discovery: CdpEndpointDiscovery;
+ readonly target: CdpEndpointTarget;
+ readonly input: InspectElectronPageInput;
+ readonly signal?: AbortSignal;
+ readonly progress?: ProgressReporter;
+}
+
+interface ScriptDraft {
+ readonly scriptId: string;
+ readonly rawUrl: string;
+ readonly hash: string;
+ readonly length: number;
+ readonly isModule: boolean;
+ readonly language: string | null;
+}
+
+/** Passively inspect one root-confined Electron file page. */
+export const inspectCdpElectronPage = async (
+ context: ElectronContext,
+): Promise => {
+ const roots = await canonicalElectronRoots(context.input.allowed_file_roots);
+ const completeness = new CdpCaptureCompleteness();
+ const scripts: ScriptDraft[] = [];
+ let mainFrameId: string | undefined;
+ let navigationDuringCapture = false;
+ const removeListener = context.connection.onEvent((event) => {
+ if (event.sessionId !== context.sessionId) return;
+ ingestScript(event, scripts, completeness);
+ if (mainFrameId !== undefined && navigatedFrameId(event) === mainFrameId)
+ navigationDuringCapture = true;
+ });
+ const startedAt = new Date().toISOString();
+ try {
+ await report(context.progress, 1, "Authorizing Electron file frames");
+ await context.connection.send(
+ "Page.enable",
+ {},
+ context.sessionId,
+ context.signal,
+ );
+ const before = await context.connection.send(
+ "Page.getFrameTree",
+ {},
+ context.sessionId,
+ context.signal,
+ );
+ const frames = await captureFrames(
+ before,
+ roots,
+ context.input.limits.max_frames,
+ completeness,
+ );
+ const main = frames[0];
+ if (main === undefined)
+ throw new BrowserObservationError(
+ "inspect_web_page",
+ "target_not_allowed",
+ );
+ mainFrameId = main.frame_id;
+ await context.connection.send(
+ "Debugger.enable",
+ { maxScriptsCacheSize: 4 * 1_024 * 1_024 },
+ context.sessionId,
+ context.signal,
+ );
+ await delayWithCancellation(context.input.observation_ms, context.signal);
+ await report(context.progress, 2, "Capturing Electron structure");
+ const resources = await captureResources(context, roots, completeness);
+ const dom = await captureDom(context, roots, completeness);
+ const normalizedScripts = await captureScripts(
+ context,
+ roots,
+ scripts,
+ completeness,
+ );
+ const after = await context.connection.send(
+ "Page.getFrameTree",
+ {},
+ context.sessionId,
+ context.signal,
+ );
+ const afterMain = await mainFilePath(after, roots);
+ if (afterMain === undefined)
+ throw new BrowserObservationError(
+ "inspect_web_page",
+ "target_not_allowed",
+ );
+ if (navigationDuringCapture || afterMain !== main.file_path)
+ throw new BrowserObservationError("inspect_web_page", "target_changed");
+ await report(context.progress, 3, "Electron inspection complete");
+ return {
+ schema_version: 1,
+ browser: context.discovery.version,
+ target: {
+ target_id: context.target.id,
+ type: context.target.type,
+ title: context.target.title.slice(0, 16_384),
+ file_path: main.file_path,
+ attached: context.target.attached,
+ },
+ capture_window: {
+ started_at: startedAt,
+ ended_at: new Date().toISOString(),
+ observation_ms: context.input.observation_ms,
+ },
+ completeness: completeness.snapshot(),
+ frames,
+ dom,
+ scripts: normalizedScripts,
+ resources,
+ limitations: [
+ "Only canonical file paths contained by an approved root are retained.",
+ "REA does not evaluate renderer JavaScript, invoke Electron APIs, navigate, click, or close the page.",
+ "Script contents require separate source-capture approval and remain byte bounded.",
+ ],
+ };
+ } finally {
+ removeListener();
+ }
+};
+
+const navigatedFrameId = (event: CdpEvent): string | undefined => {
+ const params = recordValue(event.params);
+ if (params === undefined) return undefined;
+ if (event.method === "Page.frameNavigated")
+ return stringValue(recordValue(params.frame)?.id);
+ if (event.method === "Page.navigatedWithinDocument")
+ return stringValue(params.frameId);
+ return undefined;
+};
+
+const ingestScript = (
+ event: CdpEvent,
+ scripts: ScriptDraft[],
+ completeness: CdpCaptureCompleteness,
+): void => {
+ if (event.method !== "Debugger.scriptParsed") return;
+ const value = recordValue(event.params);
+ const scriptId = stringValue(value?.scriptId);
+ const rawUrl = stringValue(value?.url);
+ if (scriptId === undefined || scriptId.length > 256) {
+ completeness.exclude("scripts", "invalid_protocol_value");
+ return;
+ }
+ if (rawUrl === undefined || rawUrl === "") {
+ completeness.exclude("scripts", "unattributed_origin");
+ return;
+ }
+ if (scripts.length >= 2_000) {
+ completeness.drop("scripts");
+ return;
+ }
+ scripts.push({
+ scriptId,
+ rawUrl,
+ hash: (stringValue(value?.hash) ?? "").slice(0, 512),
+ length: nonnegativeInteger(value?.length),
+ isModule: value?.isModule === true,
+ language: boundedText(value?.scriptLanguage, 100),
+ });
+};
+
+const captureFrames = async (
+ result: unknown,
+ roots: readonly string[],
+ maximum: number,
+ completeness: CdpCaptureCompleteness,
+): Promise => {
+ const frameTree = recordValue(requiredRecord(result).frameTree);
+ if (frameTree === undefined)
+ throw new BrowserObservationError("inspect_web_page", "protocol_error");
+ const pending: Array<{
+ readonly tree: UnknownRecord;
+ readonly parent: string | null;
+ }> = [{ tree: frameTree, parent: null }];
+ const frames: ElectronPageInspection["frames"] = [];
+ while (pending.length > 0) {
+ const current = pending.shift();
+ if (current === undefined) break;
+ const frame = recordValue(current.tree.frame);
+ const frameId = stringValue(frame?.id);
+ const path = await authorizedElectronFile(
+ stringValue(frame?.url) ?? "",
+ roots,
+ );
+ if (frameId === undefined || path === undefined) {
+ completeness.exclude("frames", "out_of_target_scope");
+ continue;
+ }
+ if (frames.length >= maximum) {
+ completeness.truncate("frames");
+ continue;
+ }
+ frames.push({
+ frame_id: frameId.slice(0, 256),
+ parent_frame_id: current.parent,
+ file_path: path,
+ });
+ for (const child of recordsValue(current.tree.childFrames))
+ pending.push({ tree: child, parent: frameId.slice(0, 256) });
+ }
+ return frames;
+};
+
+const captureResources = async (
+ context: ElectronContext,
+ roots: readonly string[],
+ completeness: CdpCaptureCompleteness,
+): Promise => {
+ const result = await context.connection.send(
+ "Page.getResourceTree",
+ {},
+ context.sessionId,
+ context.signal,
+ );
+ const root = recordValue(requiredRecord(result).frameTree);
+ if (root === undefined)
+ throw new BrowserObservationError("inspect_web_page", "protocol_error");
+ const pending = [root];
+ const resources: ElectronPageInspection["resources"] = [];
+ const seen = new Set();
+ while (pending.length > 0) {
+ const tree = pending.shift();
+ if (tree === undefined) break;
+ for (const resource of recordsValue(tree.resources)) {
+ const path = await authorizedElectronFile(
+ stringValue(resource.url) ?? "",
+ roots,
+ );
+ if (path === undefined) {
+ completeness.exclude("resources", "out_of_target_scope");
+ continue;
+ }
+ const item = {
+ file_path: path,
+ type: (stringValue(resource.type) ?? "Other").slice(0, 100),
+ mime_type: (stringValue(resource.mimeType) ?? "").slice(0, 256),
+ content_size:
+ numberValue(resource.contentSize) === undefined
+ ? null
+ : Math.max(0, numberValue(resource.contentSize) ?? 0),
+ };
+ const resourceKey = `electron_resource_${digest(item)}`;
+ if (seen.has(resourceKey)) continue;
+ seen.add(resourceKey);
+ if (resources.length >= context.input.limits.max_resources) {
+ completeness.truncate("resources");
+ continue;
+ }
+ resources.push({
+ resource_key: resourceKey,
+ ...item,
+ });
+ }
+ pending.push(...recordsValue(tree.childFrames));
+ }
+ return resources.sort((left, right) =>
+ left.resource_key.localeCompare(right.resource_key),
+ );
+};
+
+const captureDom = async (
+ context: ElectronContext,
+ roots: readonly string[],
+ completeness: CdpCaptureCompleteness,
+): Promise => {
+ const result = requiredRecord(
+ await context.connection.send(
+ "DOMSnapshot.captureSnapshot",
+ { computedStyles: [], includePaintOrder: false, includeDOMRects: false },
+ context.sessionId,
+ context.signal,
+ ),
+ );
+ const strings = Array.isArray(result.strings)
+ ? result.strings.map((value) => (typeof value === "string" ? value : ""))
+ : [];
+ const nodes: ElectronPageInspection["dom"]["nodes"] = [];
+ let total = 0;
+ for (const document of recordsValue(result.documents)) {
+ const documentUrl = stringAt(strings, document.documentURL);
+ if ((await authorizedElectronFile(documentUrl, roots)) === undefined) {
+ completeness.exclude("dom", "out_of_target_scope");
+ continue;
+ }
+ const nodeData = recordValue(document.nodes);
+ const nodeTypes = arrayValue(nodeData?.nodeType);
+ const nodeNames = arrayValue(nodeData?.nodeName);
+ const nodeValues = arrayValue(nodeData?.nodeValue);
+ const parents = arrayValue(nodeData?.parentIndex);
+ const attributes = arrayValue(nodeData?.attributes);
+ const baseIndex = nodes.length;
+ total += nodeTypes.length;
+ for (let index = 0; index < nodeTypes.length; index += 1) {
+ if (nodes.length >= context.input.limits.max_dom_nodes) continue;
+ const attributeIndexes = arrayValue(attributes[index]);
+ const parent = integer(parents[index], -1);
+ nodes.push({
+ index: nodes.length,
+ parent_index: parent < 0 ? -1 : baseIndex + parent,
+ node_type: integer(nodeTypes[index], 0),
+ node_name: stringAt(strings, nodeNames[index]).slice(0, 1_024),
+ node_value_length: Buffer.byteLength(
+ stringAt(strings, nodeValues[index]),
+ ),
+ attribute_names: attributeIndexes
+ .filter((_value, attributeIndex) => attributeIndex % 2 === 0)
+ .map((value) => stringAt(strings, value).slice(0, 1_024))
+ .slice(0, 256),
+ });
+ }
+ }
+ if (total > nodes.length) completeness.truncate("dom");
+ return { total_nodes: total, nodes };
+};
+
+const captureScripts = async (
+ context: ElectronContext,
+ roots: readonly string[],
+ scripts: readonly ScriptDraft[],
+ completeness: CdpCaptureCompleteness,
+): Promise => {
+ let total = 0;
+ let sourceBytes = 0;
+ const items: ElectronPageInspection["scripts"]["items"] = [];
+ const seen = new Set();
+ for (const script of scripts) {
+ const path = await authorizedElectronFile(script.rawUrl, roots);
+ if (path === undefined) {
+ completeness.exclude("scripts", "out_of_target_scope");
+ continue;
+ }
+ const identity = {
+ file_path: path,
+ cdp_hash: script.hash,
+ length: script.length,
+ is_module: script.isModule,
+ language: script.language,
+ };
+ const scriptKey = `electron_script_${digest(identity)}`;
+ if (seen.has(scriptKey)) continue;
+ seen.add(scriptKey);
+ total += 1;
+ if (items.length >= context.input.limits.max_scripts) {
+ completeness.drop("scripts");
+ continue;
+ }
+ let source: ElectronPageInspection["scripts"]["items"][number]["source"] = {
+ included: false,
+ reason: "source capture was not approved",
+ };
+ if (context.input.include_script_sources) {
+ if (
+ script.length > context.input.limits.max_script_source_bytes ||
+ sourceBytes + script.length >
+ context.input.limits.max_total_script_source_bytes
+ ) {
+ source = {
+ included: false,
+ reason: "script source byte limit reached",
+ };
+ completeness.truncate("script_sources");
+ } else {
+ const result = requiredRecord(
+ await context.connection.send(
+ "Debugger.getScriptSource",
+ { scriptId: script.scriptId },
+ context.sessionId,
+ context.signal,
+ ),
+ );
+ const text = stringValue(result.scriptSource) ?? "";
+ const bytes = Buffer.byteLength(text);
+ if (
+ bytes > context.input.limits.max_script_source_bytes ||
+ sourceBytes + bytes >
+ context.input.limits.max_total_script_source_bytes
+ ) {
+ source = {
+ included: false,
+ reason: "script source byte limit reached",
+ };
+ completeness.truncate("script_sources");
+ } else {
+ source = {
+ included: true,
+ artifact: createWebTextArtifact(text, "text/javascript"),
+ };
+ sourceBytes += bytes;
+ }
+ }
+ }
+ items.push({
+ script_key: scriptKey,
+ ...identity,
+ source,
+ });
+ }
+ if (!context.input.include_script_sources)
+ completeness.exclude("script_sources", "not_approved", total);
+ return {
+ total,
+ items: items.sort((left, right) =>
+ left.script_key.localeCompare(right.script_key),
+ ),
+ };
+};
+
+const mainFilePath = async (
+ result: unknown,
+ roots: readonly string[],
+): Promise => {
+ const frameTree = recordValue(requiredRecord(result).frameTree);
+ const frame = recordValue(frameTree?.frame);
+ return await authorizedElectronFile(stringValue(frame?.url) ?? "", roots);
+};
+
+const arrayValue = (value: unknown): readonly unknown[] =>
+ Array.isArray(value) ? value : [];
+
+const stringAt = (strings: readonly string[], value: unknown): string =>
+ strings[integer(value, -1)] ?? "";
+
+const integer = (value: unknown, fallback: number): number => {
+ const number = numberValue(value);
+ return number === undefined ? fallback : Math.trunc(number);
+};
+
+const nonnegativeInteger = (value: unknown): number =>
+ Math.max(0, integer(value, 0));
+
+const digest = (value: unknown): string => {
+ const encoded = canonicalize(value);
+ if (encoded === undefined) throw new TypeError("Expected canonical JSON");
+ return createHash("sha256").update(encoded).digest("hex");
+};
+
+const report = async (
+ progress: ProgressReporter | undefined,
+ completed: number,
+ message: string,
+): Promise =>
+ await progress?.report({
+ phase: "browser_observation",
+ completed,
+ total: 3,
+ message,
+ ...(completed === 3 ? { terminal: true } : {}),
+ });
diff --git a/src/browser/CdpElectronProvider.ts b/src/browser/CdpElectronProvider.ts
new file mode 100644
index 000000000..d779ca5b5
--- /dev/null
+++ b/src/browser/CdpElectronProvider.ts
@@ -0,0 +1,223 @@
+import type {
+ ExecutionOptions,
+ ProviderIdentity,
+} from "../application/AnalysisProvider.js";
+import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
+import {
+ electronPageInspectionSchema,
+ electronTargetListSchema,
+ type ElectronPageInspection,
+ type ElectronTargetList,
+ type InspectElectronPageInput,
+ type ListElectronTargetsInput,
+} from "../domain/electronObservation.js";
+import {
+ AnalysisError,
+ BrowserObservationError,
+ ProviderAdapterError,
+ type BrowserObservationOperation,
+} from "../domain/errors.js";
+import { err, ok, type Result } from "../domain/result.js";
+import { CdpConnection } from "./CdpConnection.js";
+import { discoverCdpEndpoint, type CdpEndpointTarget } from "./CdpEndpoint.js";
+import { inspectCdpElectronPage } from "./CdpElectronInspection.js";
+import {
+ authorizedElectronFile,
+ canonicalElectronRoots,
+} from "./ElectronFileScope.js";
+
+const IDENTITY: ProviderIdentity = {
+ id: "rea-cdp-electron",
+ name: "REA Electron file-page CDP observation provider",
+ version: "1",
+};
+
+/** Passive Electron provider with canonical file-root confinement. */
+export class CdpElectronProvider implements ElectronObservationPort {
+ identity(): ProviderIdentity {
+ return IDENTITY;
+ }
+
+ async listTargets(
+ input: ListElectronTargetsInput,
+ options: ExecutionOptions = {},
+ ): Promise> {
+ try {
+ const roots = await canonicalElectronRoots(input.allowed_file_roots);
+ const discovery = await discoverCdpEndpoint(
+ input.cdp_endpoint,
+ "list_browser_targets",
+ options.signal,
+ );
+ const allowed = [];
+ let outsideRoot = 0;
+ let unsupportedUrl = 0;
+ let nonPage = 0;
+ for (const target of discovery.targets) {
+ if (target.type !== "page") {
+ nonPage += 1;
+ continue;
+ }
+ const path = await authorizedElectronFile(target.url, roots);
+ if (path === undefined) {
+ if (isFileUrl(target.url)) outsideRoot += 1;
+ else unsupportedUrl += 1;
+ continue;
+ }
+ allowed.push({
+ target_id: target.id,
+ type: target.type,
+ title: target.title.slice(0, 16_384),
+ file_path: path,
+ attached: target.attached,
+ });
+ }
+ allowed.sort((left, right) =>
+ left.target_id.localeCompare(right.target_id),
+ );
+ const items = allowed.slice(input.offset, input.offset + input.limit);
+ const next = input.offset + items.length;
+ return ok(
+ electronTargetListSchema.parse({
+ schema_version: 1,
+ browser: discovery.version,
+ targets: {
+ items,
+ offset: input.offset,
+ limit: input.limit,
+ total: allowed.length,
+ next_offset: next < allowed.length ? next : null,
+ has_more: next < allowed.length,
+ },
+ excluded: {
+ outside_root: outsideRoot,
+ unsupported_url: unsupportedUrl,
+ non_page: nonPage,
+ },
+ limitations: [
+ "Only page targets whose canonical file path is contained by an approved root are listed.",
+ ],
+ }),
+ );
+ } catch (cause: unknown) {
+ return err(providerError(cause, "list_electron_targets"));
+ }
+ }
+
+ async inspectPage(
+ input: InspectElectronPageInput,
+ options: ExecutionOptions = {},
+ ): Promise> {
+ let connection: CdpConnection | undefined;
+ let sessionId: string | undefined;
+ try {
+ const roots = await canonicalElectronRoots(input.allowed_file_roots);
+ const discovery = await discoverCdpEndpoint(
+ input.cdp_endpoint,
+ "inspect_web_page",
+ options.signal,
+ );
+ const target = await authorizeTarget(
+ discovery.targets,
+ input.target_id,
+ roots,
+ );
+ connection = await CdpConnection.connect(
+ discovery.browserWebSocketUrl,
+ options.signal,
+ );
+ const attached = await connection.send(
+ "Target.attachToTarget",
+ { targetId: target.id, flatten: true },
+ undefined,
+ options.signal,
+ );
+ sessionId = attachedSessionId(attached);
+ return ok(
+ electronPageInspectionSchema.parse(
+ await inspectCdpElectronPage({
+ connection,
+ sessionId,
+ discovery,
+ target,
+ input,
+ ...(options.signal === undefined ? {} : { signal: options.signal }),
+ ...(options.progress === undefined
+ ? {}
+ : { progress: options.progress }),
+ }),
+ ),
+ );
+ } catch (cause: unknown) {
+ return err(providerError(cause, "inspect_electron_page"));
+ } finally {
+ if (connection !== undefined) {
+ if (sessionId !== undefined) await cleanup(connection, sessionId);
+ await connection.close();
+ }
+ }
+ }
+}
+
+const authorizeTarget = async (
+ targets: readonly CdpEndpointTarget[],
+ targetId: string,
+ roots: readonly string[],
+): Promise => {
+ const target = targets.find(({ id }) => id === targetId);
+ if (target === undefined)
+ throw new BrowserObservationError("inspect_web_page", "target_not_found");
+ if (
+ target.type !== "page" ||
+ (await authorizedElectronFile(target.url, roots)) === undefined
+ )
+ throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+ return target;
+};
+
+const attachedSessionId = (value: unknown): string => {
+ if (
+ typeof value !== "object" ||
+ value === null ||
+ !("sessionId" in value) ||
+ typeof value.sessionId !== "string" ||
+ value.sessionId.length > 256
+ )
+ throw new BrowserObservationError("inspect_web_page", "protocol_error");
+ return value.sessionId;
+};
+
+const cleanup = async (
+ connection: CdpConnection,
+ sessionId: string,
+): Promise => {
+ for (const method of ["Debugger.disable", "Page.disable"])
+ try {
+ await connection.send(method, {}, sessionId);
+ } catch {
+ // Detach remains the final non-destructive cleanup boundary.
+ }
+ try {
+ await connection.send("Target.detachFromTarget", { sessionId });
+ } catch {
+ // Closing REA's socket never closes the Electron target.
+ }
+};
+
+const isFileUrl = (value: string): boolean => {
+ try {
+ return new URL(value).protocol === "file:";
+ } catch {
+ return false;
+ }
+};
+
+const providerError = (
+ cause: unknown,
+ operation: BrowserObservationOperation,
+): AnalysisError =>
+ cause instanceof BrowserObservationError && cause.operation !== operation
+ ? new BrowserObservationError(operation, cause.reason, { cause })
+ : cause instanceof AnalysisError
+ ? cause
+ : new ProviderAdapterError(IDENTITY.id, operation, { cause });
diff --git a/src/browser/CdpEndpoint.ts b/src/browser/CdpEndpoint.ts
index d63a5e32b..b09c9d1ca 100644
--- a/src/browser/CdpEndpoint.ts
+++ b/src/browser/CdpEndpoint.ts
@@ -7,6 +7,7 @@ import {
AnalysisError,
AnalysisTimeoutError,
BrowserObservationError,
+ type BrowserObservationOperation,
} from "../domain/errors.js";
const HTTP_TIMEOUT_MS = 5_000;
@@ -45,12 +46,10 @@ export interface CdpEndpointDiscovery {
readonly targets: readonly CdpEndpointTarget[];
}
-type BrowserOperation = "list_browser_targets" | "inspect_web_page";
-
/** Read bounded CDP discovery endpoints without following redirects. */
export const discoverCdpEndpoint = async (
endpoint: string,
- operation: BrowserOperation,
+ operation: BrowserObservationOperation,
signal?: AbortSignal,
): Promise => {
const versionInput = await readJson(
@@ -95,7 +94,7 @@ export const discoverCdpEndpoint = async (
const parseEndpointValue = (
schema: z.ZodType,
input: unknown,
- operation: BrowserOperation,
+ operation: BrowserObservationOperation,
): Output => {
const parsed = schema.safeParse(input);
if (!parsed.success)
@@ -108,7 +107,7 @@ const parseEndpointValue = (
const safeBrowserWebSocketUrl = (
endpoint: string,
reported: string,
- operation: BrowserOperation,
+ operation: BrowserObservationOperation,
): string => {
let parsed: URL;
try {
@@ -136,7 +135,7 @@ const safeBrowserWebSocketUrl = (
const readJson = async (
url: URL,
maximumBytes: number,
- operation: BrowserOperation,
+ operation: BrowserObservationOperation,
signal?: AbortSignal,
): Promise =>
await new Promise((resolve, reject) => {
@@ -196,7 +195,7 @@ const readJson = async (
const endpointFailure = (
cause: unknown,
- operation: BrowserOperation,
+ operation: BrowserObservationOperation,
signal?: AbortSignal,
): AnalysisError => {
if (cause instanceof AnalysisError) return cause;
diff --git a/src/browser/CdpObservationSession.ts b/src/browser/CdpObservationSession.ts
new file mode 100644
index 000000000..2016f651d
--- /dev/null
+++ b/src/browser/CdpObservationSession.ts
@@ -0,0 +1,416 @@
+import type { ProgressReporter } from "../application/ProgressReporter.js";
+import type {
+ ObserveWebSessionInput,
+ WebObservationSession,
+} from "../domain/browserSession.js";
+import { BrowserObservationError } from "../domain/errors.js";
+import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js";
+import { CdpConnection, type CdpEvent } from "./CdpConnection.js";
+import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
+import {
+ allowedSanitizedUrl,
+ delayWithCancellation,
+ isHttpUrl,
+ numberValue,
+ recordValue,
+ stringValue,
+ type UnknownRecord,
+} from "./CdpCaptureValues.js";
+import { mainFrameUrl } from "./CdpCaptureDocuments.js";
+
+interface ObservationContext {
+ readonly connection: CdpConnection;
+ readonly sessionId: string;
+ readonly discovery: CdpEndpointDiscovery;
+ readonly target: CdpEndpointTarget;
+ readonly input: ObserveWebSessionInput;
+ readonly signal?: AbortSignal;
+ readonly progress?: ProgressReporter;
+}
+
+type EndReason = WebObservationSession["window"]["end_reason"];
+type TimelineEvent = WebObservationSession["timeline"][number];
+
+/** Observe external user actions without rejecting approved same-origin navigation. */
+export const observeCdpSession = async (
+ context: ObservationContext,
+): Promise => {
+ const allowedOrigins = new Set(context.input.allowed_origins);
+ const initial = await authorizedFrame(context, allowedOrigins);
+ const initialUrl = mainFrameUrl(initial) ?? "";
+ const mainFrameId = frameId(initial);
+ if (mainFrameId === undefined)
+ throw new BrowserObservationError("inspect_web_page", "protocol_error");
+ const capture = new TimelineCapture(
+ context.input.max_timeline_events,
+ allowedOrigins,
+ mainFrameId,
+ initialUrl,
+ );
+ const removeListener = context.connection.onEvent((event) => {
+ if (event.sessionId === context.sessionId) capture.ingest(event);
+ });
+ try {
+ await context.connection.send(
+ "Page.enable",
+ {},
+ context.sessionId,
+ context.signal,
+ );
+ await context.connection.send(
+ "Network.enable",
+ { maxTotalBufferSize: 1_024 * 1_024 },
+ context.sessionId,
+ context.signal,
+ );
+ await context.connection.send(
+ "Page.setLifecycleEventsEnabled",
+ { enabled: true },
+ context.sessionId,
+ context.signal,
+ );
+ const armedAt = new Date().toISOString();
+ await context.progress?.report({
+ phase: "browser_observation",
+ completed: 1,
+ total: 2,
+ message:
+ "Browser observation armed; perform the approved user action now",
+ });
+ let endReason = await waitForWindow(
+ context.input.observation_ms,
+ capture,
+ context.signal,
+ );
+ if (endReason === "window_elapsed")
+ endReason = await captureFinalUrl(context, capture, allowedOrigins);
+ await context.progress?.report({
+ phase: "browser_observation",
+ completed: 2,
+ total: 2,
+ message: "Browser observation window ended",
+ terminal: true,
+ });
+ return {
+ schema_version: 1,
+ browser: context.discovery.version,
+ target: {
+ target_id: context.target.id,
+ initial_url: allowedSanitizedUrl(initialUrl, allowedOrigins)?.url ?? "",
+ final_url: capture.finalUrl,
+ },
+ window: {
+ armed_at: armedAt,
+ ended_at: new Date().toISOString(),
+ requested_ms: context.input.observation_ms,
+ end_reason: endReason,
+ },
+ timeline: capture.timeline,
+ completeness: capture.completeness.snapshot(),
+ limitations: [
+ "The timeline begins after REA attaches; earlier navigation and network activity is unavailable.",
+ "Only navigation metadata is retained; headers, bodies, cookies, console values, and payloads are not captured by this tool.",
+ "An out-of-policy destination ends collection immediately and is recorded without its URL.",
+ ],
+ };
+ } finally {
+ removeListener();
+ }
+};
+
+class TimelineCapture {
+ readonly timeline: TimelineEvent[] = [];
+ readonly completeness = new CdpCaptureCompleteness(["timeline"]);
+ finalUrl: string | null;
+ #sequence = 0;
+ #pendingReload = false;
+ #endReason: EndReason | undefined;
+ readonly #listeners = new Set<(reason: EndReason) => void>();
+
+ constructor(
+ private readonly maximum: number,
+ private readonly allowedOrigins: ReadonlySet,
+ private readonly mainFrameId: string,
+ initialUrl: string,
+ ) {
+ this.finalUrl =
+ allowedSanitizedUrl(initialUrl, allowedOrigins)?.url ?? null;
+ }
+
+ ingest(event: CdpEvent): void {
+ if (this.#endReason !== undefined) return;
+ const params = recordValue(event.params);
+ if (params === undefined) return;
+ switch (event.method) {
+ case "Page.frameRequestedNavigation":
+ this.#navigationRequested(params);
+ break;
+ case "Page.frameNavigated":
+ this.#navigationCommitted(params);
+ break;
+ case "Page.navigatedWithinDocument":
+ this.#sameDocument(params);
+ break;
+ case "Network.requestWillBeSent":
+ this.#redirect(params);
+ break;
+ case "Network.loadingFailed":
+ this.#loadingFailed(params);
+ break;
+ case "Page.lifecycleEvent":
+ this.#lifecycle(params);
+ break;
+ case "Inspector.targetCrashed":
+ case "Target.detachedFromTarget":
+ this.#add("target_terminated", params, null, null, "target_terminated");
+ this.end("target_terminated");
+ break;
+ }
+ }
+
+ onEnd(listener: (reason: EndReason) => void): () => void {
+ if (this.#endReason !== undefined) listener(this.#endReason);
+ else this.#listeners.add(listener);
+ return () => this.#listeners.delete(listener);
+ }
+
+ end(reason: EndReason): void {
+ if (this.#endReason !== undefined) return;
+ this.#endReason = reason;
+ for (const listener of this.#listeners) listener(reason);
+ this.#listeners.clear();
+ }
+
+ setFinalUrl(rawUrl: string): void {
+ const destination = scopedUrl(rawUrl, this.allowedOrigins);
+ this.finalUrl = destination.scope === "approved" ? destination.url : null;
+ }
+
+ #navigationRequested(params: UnknownRecord): void {
+ if (stringValue(params.frameId) !== this.mainFrameId) return;
+ const reason = safeDetail(params.reason);
+ this.#pendingReload = reason === "reload";
+ this.#add(
+ "navigation_requested",
+ params,
+ stringValue(params.url),
+ null,
+ reason,
+ );
+ }
+
+ #navigationCommitted(params: UnknownRecord): void {
+ const frame = recordValue(params.frame);
+ if (stringValue(frame?.id) !== this.mainFrameId) return;
+ const rawUrl = stringValue(frame?.url);
+ const destination = scopedUrl(rawUrl, this.allowedOrigins);
+ this.#add(
+ this.#pendingReload ? "same_origin_reload" : "navigation_committed",
+ { ...params, frameId: frame?.id, loaderId: frame?.loaderId },
+ rawUrl,
+ null,
+ safeDetail(frame?.transitionType),
+ );
+ this.#pendingReload = false;
+ if (destination.scope === "approved") this.finalUrl = destination.url;
+ else {
+ this.finalUrl = null;
+ this.completeness.exclude("timeline", "out_of_target_scope");
+ this.end("target_left_scope");
+ }
+ }
+
+ #sameDocument(params: UnknownRecord): void {
+ if (stringValue(params.frameId) !== this.mainFrameId) return;
+ const rawUrl = stringValue(params.url);
+ const destination = scopedUrl(rawUrl, this.allowedOrigins);
+ this.#add("same_document_navigation", params, rawUrl, null, null);
+ if (destination.scope === "approved") this.finalUrl = destination.url;
+ else {
+ this.finalUrl = null;
+ this.completeness.exclude("timeline", "out_of_target_scope");
+ this.end("target_left_scope");
+ }
+ }
+
+ #redirect(params: UnknownRecord): void {
+ if (
+ stringValue(params.frameId) !== this.mainFrameId ||
+ recordValue(params.redirectResponse) === undefined
+ )
+ return;
+ const request = recordValue(params.request);
+ const rawUrl = stringValue(request?.url);
+ const destination = scopedUrl(rawUrl, this.allowedOrigins);
+ this.#add(
+ "redirect",
+ params,
+ rawUrl,
+ stringValue(params.requestId) ?? null,
+ null,
+ );
+ if (destination.scope !== "approved") {
+ this.completeness.exclude("timeline", "out_of_target_scope");
+ this.end("target_left_scope");
+ }
+ }
+
+ #loadingFailed(params: UnknownRecord): void {
+ const frame = stringValue(params.frameId);
+ if (frame !== undefined && frame !== this.mainFrameId) return;
+ this.#add(
+ "load_failed",
+ params,
+ null,
+ stringValue(params.requestId) ?? null,
+ safeNetworkError(params.errorText),
+ );
+ }
+
+ #lifecycle(params: UnknownRecord): void {
+ if (stringValue(params.frameId) !== this.mainFrameId) return;
+ this.#add("lifecycle", params, null, null, safeDetail(params.name));
+ }
+
+ #add(
+ type: TimelineEvent["type"],
+ params: UnknownRecord,
+ rawUrl: string | null | undefined,
+ requestId: string | null,
+ detail: string | null,
+ ): void {
+ const destination =
+ rawUrl == null ? null : scopedUrl(rawUrl, this.allowedOrigins);
+ if (this.timeline.length >= this.maximum) {
+ this.completeness.drop("timeline_events");
+ return;
+ }
+ this.#sequence += 1;
+ this.timeline.push({
+ sequence: this.#sequence,
+ type,
+ timestamp: Math.max(0, numberValue(params.timestamp) ?? 0),
+ frame_id: boundedId(params.frameId),
+ loader_id: boundedId(params.loaderId),
+ request_id: requestId?.slice(0, 256) ?? null,
+ url: destination?.scope === "approved" ? destination.url : null,
+ destination_scope: destination?.scope ?? null,
+ detail,
+ });
+ }
+}
+
+const waitForWindow = async (
+ durationMs: number,
+ capture: TimelineCapture,
+ signal?: AbortSignal,
+): Promise =>
+ await new Promise((resolve, reject) => {
+ let settled = false;
+ let removeEnd = (): void => {};
+ const finish = (reason: EndReason): void => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ signal?.removeEventListener("abort", onAbort);
+ removeEnd();
+ resolve(reason);
+ };
+ const onAbort = (): void => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ removeEnd();
+ reject(signal?.reason ?? new Error("browser observation cancelled"));
+ };
+ const timer = setTimeout(() => finish("window_elapsed"), durationMs);
+ removeEnd = capture.onEnd(finish);
+ signal?.addEventListener("abort", onAbort, { once: true });
+ if (signal?.aborted === true) onAbort();
+ });
+
+const authorizedFrame = async (
+ context: ObservationContext,
+ allowedOrigins: ReadonlySet,
+): Promise => {
+ for (let attempt = 0; attempt < 80; attempt += 1) {
+ const result = await context.connection.send(
+ "Page.getFrameTree",
+ {},
+ context.sessionId,
+ context.signal,
+ );
+ const url = mainFrameUrl(result);
+ if (allowedSanitizedUrl(url, allowedOrigins) !== undefined) return result;
+ if (isHttpUrl(url))
+ throw new BrowserObservationError(
+ "inspect_web_page",
+ "target_not_allowed",
+ );
+ await delayWithCancellation(25, context.signal);
+ }
+ throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+};
+
+const captureFinalUrl = async (
+ context: ObservationContext,
+ capture: TimelineCapture,
+ allowedOrigins: ReadonlySet,
+): Promise => {
+ const result = await context.connection.send(
+ "Page.getFrameTree",
+ {},
+ context.sessionId,
+ context.signal,
+ );
+ const url = mainFrameUrl(result);
+ if (
+ url !== undefined &&
+ allowedSanitizedUrl(url, allowedOrigins) !== undefined
+ ) {
+ capture.setFinalUrl(url);
+ return "window_elapsed";
+ }
+ capture.finalUrl = null;
+ capture.completeness.exclude(
+ "timeline",
+ url === undefined ? "invalid_protocol_value" : "out_of_target_scope",
+ );
+ return "target_left_scope";
+};
+
+const frameId = (result: unknown): string | undefined =>
+ stringValue(
+ recordValue(recordValue(recordValue(result)?.frameTree)?.frame)?.id,
+ );
+
+const scopedUrl = (
+ value: string | undefined,
+ allowedOrigins: ReadonlySet,
+): {
+ readonly url: string | null;
+ readonly scope: "approved" | "outside_policy" | "unsupported";
+} => {
+ const allowed = allowedSanitizedUrl(value, allowedOrigins);
+ if (allowed !== undefined) return { url: allowed.url, scope: "approved" };
+ return isHttpUrl(value)
+ ? { url: null, scope: "outside_policy" }
+ : { url: null, scope: "unsupported" };
+};
+
+const boundedId = (value: unknown): string | null =>
+ stringValue(value)?.slice(0, 256) ?? null;
+
+const safeDetail = (value: unknown): string | null => {
+ const detail = stringValue(value)?.toLowerCase();
+ return detail !== undefined && /^[a-z0-9_.:-]{1,100}$/u.test(detail)
+ ? detail
+ : null;
+};
+
+const safeNetworkError = (value: unknown): string | null => {
+ const error = stringValue(value);
+ return error !== undefined && /^net::ERR_[A-Z0-9_]{1,100}$/u.test(error)
+ ? error
+ : null;
+};
diff --git a/src/browser/CdpPageCapture.ts b/src/browser/CdpPageCapture.ts
index 5fdaba4b6..45418e704 100644
--- a/src/browser/CdpPageCapture.ts
+++ b/src/browser/CdpPageCapture.ts
@@ -4,6 +4,11 @@ import type {
} from "../domain/browserObservation.js";
import type { ProgressReporter } from "../application/ProgressReporter.js";
import { BrowserObservationError } from "../domain/errors.js";
+import {
+ reconcileCapturedWebScript,
+ stableWebResources,
+ stableWebScriptKey,
+} from "../domain/webInventory.js";
import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js";
import { CdpConnection } from "./CdpConnection.js";
import { CdpCaptureEvents } from "./CdpCaptureEvents.js";
@@ -14,6 +19,7 @@ import {
captureDom,
captureFrames,
captureResources,
+ type CapturedResource,
mainFrameUrl,
} from "./CdpCaptureDocuments.js";
import {
@@ -27,6 +33,7 @@ import {
sourceResult,
stringValue,
} from "./CdpCaptureValues.js";
+import type { WebSourceMapRequest } from "./WebSourceMapFetcher.js";
interface CaptureContext {
readonly connection: CdpConnection;
@@ -43,7 +50,6 @@ interface CaptureState {
readonly events: CdpCaptureEvents;
readonly allowedOrigins: ReadonlySet;
readonly limitations: string[];
- readonly truncatedSections: Set;
readonly startedAt: string;
}
@@ -58,10 +64,20 @@ interface CapturedSections {
readonly storage: WebPageInspection["storage"];
}
+export interface CapturedPage {
+ readonly inspection: WebPageInspection;
+ readonly sourceMapRequests: readonly WebSourceMapRequest[];
+}
+
+interface CapturedScripts {
+ readonly inventory: WebPageInspection["scripts"];
+ readonly sourceMapRequests: readonly WebSourceMapRequest[];
+}
+
/** Capture and normalize one attached page without evaluating page JavaScript. */
export const capturePage = async (
context: CaptureContext,
-): Promise => {
+): Promise => {
const allowedOrigins = new Set(context.input.allowed_origins);
const events = new CdpCaptureEvents(context.input, allowedOrigins);
const removeListener = context.connection.onEvent((event) => {
@@ -74,11 +90,10 @@ export const capturePage = async (
allowedOrigins,
limitations: [
"Observation starts when REA attaches; prior network and console activity is unavailable.",
- "Network headers, request bodies, response bodies, cookies, storage values, console values, and WebSocket payloads are not retained.",
+ "Raw network headers, bodies, cookies, storage values, console objects, and WebSocket payloads are never retained; separately approved captures retain only bounded redacted text or value-free shapes.",
"Source maps are reported only as declarative URLs and are not fetched.",
"URL-less scripts and console events without an allowed source URL are excluded because their origin cannot be proven.",
],
- truncatedSections: new Set(),
startedAt: new Date().toISOString(),
};
try {
@@ -90,19 +105,22 @@ export const capturePage = async (
const captureAuthorizedPage = async (
state: CaptureState,
-): Promise => {
- const { context, allowedOrigins, limitations, truncatedSections } = state;
+): Promise => {
+ const { context, allowedOrigins, limitations } = state;
const { connection, sessionId, input, signal } = context;
await authorizeObservationWindow(state);
+ await captureJsonResponseBodies(state);
const frameResult = await authorizedFrameTree(context, allowedOrigins);
const attachedUrl = mainFrameUrl(frameResult) ?? "";
const frameCapture = captureFrames(
frameResult,
allowedOrigins,
input.limits.max_frames,
+ state.events.completeness,
);
const frames = frameCapture.items;
- if (frameCapture.total > frames.length) truncatedSections.add("frames");
+ if (frameCapture.total > frames.length)
+ state.events.completeness.truncate("frames");
const captureFrame = frames[0];
if (captureFrame === undefined)
throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
@@ -111,38 +129,39 @@ const captureAuthorizedPage = async (
await connection.send("Page.getResourceTree", {}, sessionId, signal),
allowedOrigins,
input.limits.max_resources,
+ state.events.completeness,
);
if (resourceCapture.total > resourceCapture.items.length)
- truncatedSections.add("resources");
- const dom = await capturePageDom(state);
- if (dom.total > dom.nodes.length) truncatedSections.add("dom");
- const accessibility = await accessibilityForFrames(
- context,
- frames,
- limitations,
+ state.events.completeness.truncate("resources");
+ const resources = stableWebResources(
+ resourceCapture.items.map(publicResource),
);
+ const dom = await capturePageDom(state);
+ if (dom.total > dom.nodes.length) state.events.completeness.truncate("dom");
+ const accessibility = await accessibilityForFrames(state, frames);
if (accessibility.total > accessibility.nodes.length)
- truncatedSections.add("accessibility");
+ state.events.completeness.truncate("accessibility");
const scripts = await captureScripts(
context,
state.events,
- truncatedSections,
+ resourceCapture.items,
+ resources,
);
const workerCapture = await captureWorkers(
- context,
- allowedOrigins,
+ state,
new Set(frames.map((frame) => frame.frame_id)),
- limitations,
);
if (workerCapture.total > workerCapture.items.length)
- truncatedSections.add("workers");
+ state.events.completeness.truncate("workers");
const storageCapture = await captureStorage(
context,
frames[0]?.origin ?? new URL(attachedUrl).origin,
limitations,
);
- if (storageCapture.truncated) truncatedSections.add("storage_keys");
- if (state.events.dropped > 0) truncatedSections.add("events");
+ if (storageCapture.truncated)
+ state.events.completeness.truncate("storage_keys");
+ if (!input.include_storage_keys)
+ state.events.completeness.exclude("storage_keys", "not_approved", null);
const completedFrameResult = await authorizedFrameTree(
context,
allowedOrigins,
@@ -153,16 +172,42 @@ const captureAuthorizedPage = async (
if (state.events.navigationDuringCapture || completedUrl !== attachedUrl)
throw new BrowserObservationError("inspect_web_page", "target_changed");
await report(context.progress, 3, "Normalizing browser evidence");
- return normalizedInspection(state, {
- attachedUrl,
- frames,
- dom,
- accessibility,
- scripts,
- resources: resourceCapture.items,
- workers: workerCapture.items,
- storage: storageCapture.value,
- });
+ return {
+ inspection: normalizedInspection(state, {
+ attachedUrl,
+ frames,
+ dom,
+ accessibility,
+ scripts: scripts.inventory,
+ resources,
+ workers: workerCapture.items,
+ storage: storageCapture.value,
+ }),
+ sourceMapRequests: scripts.sourceMapRequests,
+ };
+};
+
+const captureJsonResponseBodies = async (
+ state: CaptureState,
+): Promise => {
+ const requestIds = state.events.responseBodyRequestIds();
+ for (let index = 0; index < requestIds.length; index += 1) {
+ const requestId = requestIds[index];
+ if (requestId === undefined) continue;
+ const result = await optionalCdpCommand(
+ state.context,
+ "Network.getResponseBody",
+ { requestId },
+ state.limitations,
+ );
+ if (result !== undefined) {
+ state.events.ingestResponseBody(requestId, result);
+ continue;
+ }
+ for (const remaining of requestIds.slice(index))
+ state.events.responseBodyUnavailable(remaining);
+ return;
+ }
};
const authorizeObservationWindow = async (
@@ -199,14 +244,19 @@ const capturePageDom = async (
context.sessionId,
context.signal,
);
- return captureDom(result, allowedOrigins, context.input);
+ return captureDom(
+ result,
+ allowedOrigins,
+ context.input,
+ state.events.completeness,
+ );
};
const normalizedInspection = (
state: CaptureState,
captured: CapturedSections,
): WebPageInspection => ({
- schema_version: 1,
+ schema_version: 2,
browser: state.context.discovery.version,
target: normalizedTarget(
state.context.target,
@@ -218,15 +268,12 @@ const normalizedInspection = (
ended_at: new Date().toISOString(),
observation_ms: state.context.input.observation_ms,
},
- completeness: {
- status: state.truncatedSections.size === 0 ? "complete" : "truncated",
- truncated_sections: [...state.truncatedSections].sort(),
- dropped_events: state.events.dropped,
- },
+ completeness: state.events.completeness.snapshot(),
frames: [...captured.frames],
dom: { total_nodes: captured.dom.total, nodes: [...captured.dom.nodes] },
accessibility: {
total_nodes: captured.accessibility.total,
+ text_capture: captured.accessibility.textCapture,
nodes: [...captured.accessibility.nodes],
},
scripts: captured.scripts,
@@ -243,6 +290,16 @@ const normalizedInspection = (
prior_activity_available: false,
},
workers: [...captured.workers],
+ metadata: {
+ responses: [...state.events.responseMetadata],
+ dom_urls: [...captured.dom.urls],
+ agent_hints: deduplicatedAgentHints([
+ ...state.events.agentHints,
+ ...captured.dom.agentHints,
+ ]),
+ excluded_dom_urls: captured.dom.excludedUrls,
+ headers_allowlisted: true,
+ },
storage: captured.storage,
limitations: state.limitations,
});
@@ -295,12 +352,12 @@ const enableObservationDomains = async (
};
const accessibilityForFrames = async (
- context: CaptureContext,
+ state: CaptureState,
frames: readonly { readonly frame_id: string }[],
- limitations: string[],
): Promise> => {
- const nodes: WebPageInspection["accessibility"]["nodes"] = [];
- let total = 0;
+ const { context, limitations, events } = state;
+ const results: unknown[] = [];
+ let unavailable = false;
for (const frame of frames) {
const result = await optionalCdpCommand(
context,
@@ -308,24 +365,45 @@ const accessibilityForFrames = async (
{ depth: 32, frameId: frame.frame_id },
limitations,
);
- if (result === undefined) continue;
- const capture = captureAccessibility(
- [result],
- Math.max(0, context.input.limits.max_ax_nodes - nodes.length),
- );
- total += capture.total;
- nodes.push(...capture.nodes);
+ if (result === undefined) unavailable = true;
+ else results.push(result);
}
- return { total, nodes };
+ if (unavailable) events.completeness.unavailable("accessibility");
+ const capture = captureAccessibility(
+ results,
+ context.input.limits.max_ax_nodes,
+ {
+ includeText: context.input.include_accessibility_text,
+ maximumFieldBytes: context.input.limits.max_ax_text_field_bytes,
+ maximumTotalBytes: context.input.limits.max_total_ax_text_bytes,
+ ...(results.length === 0 && unavailable ? { unavailable: true } : {}),
+ },
+ );
+ if (!context.input.include_accessibility_text)
+ events.completeness.exclude(
+ "accessibility",
+ "not_approved",
+ capture.textCapture.excluded_fields,
+ );
+ if (capture.textCapture.status === "truncated")
+ events.completeness.truncate("accessibility");
+ return capture;
};
const captureScripts = async (
context: CaptureContext,
events: CdpCaptureEvents,
- truncatedSections: Set,
-): Promise => {
+ rawResources: readonly CapturedResource[],
+ resources: WebPageInspection["resources"],
+): Promise => {
let totalSourceBytes = 0;
- const items: WebPageInspection["scripts"]["items"] = [];
+ const drafts: {
+ readonly item: Omit<
+ WebPageInspection["scripts"]["items"][number],
+ "script_key"
+ >;
+ readonly sourceMapRawUrl: string | null;
+ }[] = [];
for (const script of events.scripts.values()) {
let source: WebPageInspection["scripts"]["items"][number]["source"] =
sourceExcluded("source capture was not approved");
@@ -334,13 +412,13 @@ const captureScripts = async (
source = sourceExcluded(
"declared script length exceeds per-script limit",
);
- truncatedSections.add("script_sources");
+ events.completeness.truncate("script_sources");
} else if (
totalSourceBytes + script.length >
context.input.limits.max_total_script_source_bytes
) {
source = sourceExcluded("total script source limit reached");
- truncatedSections.add("script_sources");
+ events.completeness.truncate("script_sources");
} else {
const result = requiredRecord(
await context.connection.send(
@@ -360,37 +438,103 @@ const captureScripts = async (
source = sourceExcluded(
"actual source exceeds configured byte limits",
);
- truncatedSections.add("script_sources");
+ events.completeness.truncate("script_sources");
} else {
source = sourceResult(content);
totalSourceBytes += bytes;
}
}
}
- items.push({
- script_id: script.scriptId,
+ const inventoryScript = {
url: script.url,
- origin: script.origin,
cdp_hash: script.hash,
length: script.length,
is_module: script.isModule,
language: script.language,
source_map_url: script.sourceMapUrl,
- source,
+ };
+ drafts.push({
+ item: {
+ ...inventoryScript,
+ origin: script.origin,
+ resource_reconciliation: reconcileCapturedWebScript(
+ { ...inventoryScript, rawUrl: script.rawUrl },
+ rawResources,
+ resources,
+ ),
+ source,
+ },
+ sourceMapRawUrl: script.sourceMapRawUrl,
});
}
- return { total: events.scripts.size, items };
+ if (!context.input.include_script_sources)
+ events.completeness.exclude(
+ "script_sources",
+ "not_approved",
+ events.scripts.size,
+ );
+ const keyed = drafts.map((draft) => ({
+ ...draft,
+ base: stableWebScriptKey(draft.item),
+ }));
+ keyed.sort(
+ (left, right) =>
+ left.base.localeCompare(right.base) ||
+ sourceDigest(left.item.source).localeCompare(
+ sourceDigest(right.item.source),
+ ),
+ );
+ const totals = new Map();
+ for (const { base } of keyed) totals.set(base, (totals.get(base) ?? 0) + 1);
+ const seen = new Map();
+ const sourceMapRequests: WebSourceMapRequest[] = [];
+ const items = keyed.map(({ base, item, sourceMapRawUrl }) => {
+ const occurrence = (seen.get(base) ?? 0) + 1;
+ seen.set(base, occurrence);
+ const scriptKey =
+ totals.get(base) === 1 ? base : `${base}_${String(occurrence)}`;
+ if (item.source_map_url !== null && sourceMapRawUrl !== null)
+ sourceMapRequests.push({
+ scriptKey,
+ declaredUrl: item.source_map_url,
+ fetchUrl: sourceMapRawUrl,
+ });
+ return { script_key: scriptKey, ...item };
+ });
+ return {
+ inventory: { total: events.scripts.size, items },
+ sourceMapRequests,
+ };
+};
+
+const sourceDigest = (
+ source: WebPageInspection["scripts"]["items"][number]["source"],
+): string => (source.included ? source.artifact.sha256 : source.reason);
+
+const publicResource = ({ rawUrl: _rawUrl, ...resource }: CapturedResource) =>
+ resource;
+
+const deduplicatedAgentHints = (
+ hints: WebPageInspection["metadata"]["agent_hints"],
+): WebPageInspection["metadata"]["agent_hints"] => {
+ const seen = new Set();
+ return hints.filter((hint) => {
+ const key = `${hint.mechanism}\0${hint.declaration}\0${hint.url ?? ""}`;
+ if (seen.has(key)) return false;
+ seen.add(key);
+ return true;
+ });
};
const captureWorkers = async (
- context: CaptureContext,
- allowedOrigins: ReadonlySet,
+ state: CaptureState,
frameIds: ReadonlySet,
- limitations: string[],
): Promise<{
readonly total: number;
readonly items: WebPageInspection["workers"];
}> => {
+ const { context, allowedOrigins, limitations, events } = state;
+ const completeness = events.completeness;
const result = await optionalCdpCommand(
{ ...context, sessionId: undefined },
"Target.getTargets",
@@ -399,6 +543,7 @@ const captureWorkers = async (
);
const items: WebPageInspection["workers"] = [];
let total = 0;
+ if (result === undefined) completeness.unavailable("workers");
for (const target of recordsValue(recordValue(result)?.targetInfos)) {
const type = stringValue(target.type) ?? "";
const url = allowedSanitizedUrl(target.url, allowedOrigins);
@@ -406,8 +551,23 @@ const captureWorkers = async (
stringValue(target.openerId) === context.target.id ||
(stringValue(target.parentFrameId) !== undefined &&
frameIds.has(stringValue(target.parentFrameId) ?? ""));
- if (!type.includes("worker") || url === undefined || !relatedToPage)
+ if (!type.includes("worker")) continue;
+ if (!relatedToPage) {
+ completeness.exclude("workers", "out_of_target_scope");
continue;
+ }
+ if (url === undefined) {
+ const rawUrl = stringValue(target.url);
+ completeness.exclude(
+ "workers",
+ rawUrl === undefined || rawUrl === ""
+ ? "unattributed_origin"
+ : isHttpUrl(rawUrl)
+ ? "disallowed_origin"
+ : "unsupported_url",
+ );
+ continue;
+ }
total += 1;
if (items.length >= context.input.limits.max_workers) continue;
items.push({
diff --git a/src/browser/CdpSafeMetadata.ts b/src/browser/CdpSafeMetadata.ts
new file mode 100644
index 000000000..5f9c80107
--- /dev/null
+++ b/src/browser/CdpSafeMetadata.ts
@@ -0,0 +1,277 @@
+import type { WebPageInspection } from "../domain/browserObservation.js";
+import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
+import {
+ numberValue,
+ stringValue,
+ type UnknownRecord,
+} from "./CdpCaptureValues.js";
+
+type ResponseMetadata = WebPageInspection["metadata"]["responses"][number];
+type LinkMetadata = ResponseMetadata["links"][number];
+type AgentHint = WebPageInspection["metadata"]["agent_hints"][number];
+
+/** Normalize an allowlisted subset of response metadata and discard raw headers. */
+export const safeResponseMetadata = (
+ requestId: string,
+ url: string,
+ response: UnknownRecord,
+ allowedOrigins: ReadonlySet,
+): {
+ readonly response: ResponseMetadata;
+ readonly agentHints: AgentHint[];
+} => {
+ const headers = normalizedHeaders(response.headers);
+ const links = parseLinks(headers.get("link"), url, allowedOrigins);
+ const csp = parseCsp(
+ headers.get("content-security-policy"),
+ url,
+ allowedOrigins,
+ );
+ const agentHints = [
+ ...links.flatMap((link) =>
+ link.rel.some(isAgentRel)
+ ? [agentHint("link_rel", link.rel.join(" "), link.href)]
+ : [],
+ ),
+ ...agentHeaderNames.flatMap((name) =>
+ headers.has(name) ? [agentHint("response_header", name, null)] : [],
+ ),
+ ...wellKnownHint(url),
+ ];
+ return {
+ response: {
+ request_id: requestId,
+ url,
+ mime_type: boundedHeader(stringValue(response.mimeType)),
+ content_length: nonnegativeInteger(headers.get("content-length")),
+ content_encoding: boundedHeader(headers.get("content-encoding")),
+ csp,
+ links,
+ policies: {
+ coop: policyToken(headers.get("cross-origin-opener-policy")),
+ coep: policyToken(headers.get("cross-origin-embedder-policy")),
+ corp: policyToken(headers.get("cross-origin-resource-policy")),
+ referrer_policy: policyToken(headers.get("referrer-policy")),
+ x_content_type_options: policyToken(
+ headers.get("x-content-type-options"),
+ ),
+ permissions_policy_features: permissionFeatures(
+ headers.get("permissions-policy"),
+ ),
+ },
+ },
+ agentHints,
+ };
+};
+
+const normalizedHeaders = (value: unknown): ReadonlyMap => {
+ if (typeof value !== "object" || value === null || Array.isArray(value))
+ return new Map();
+ const headers = new Map();
+ for (const [name, raw] of Object.entries(value).slice(0, 500)) {
+ const normalized = name.toLowerCase().slice(0, 256);
+ const header =
+ typeof raw === "string"
+ ? raw
+ : typeof raw === "number" && Number.isFinite(raw)
+ ? String(raw)
+ : undefined;
+ if (header !== undefined) headers.set(normalized, header.slice(0, 65_536));
+ }
+ return headers;
+};
+
+const parseCsp = (
+ value: string | undefined,
+ baseUrl: string,
+ allowedOrigins: ReadonlySet,
+): ResponseMetadata["csp"] => {
+ const directives: ResponseMetadata["csp"]["directives"] = [];
+ let nonceCount = 0;
+ let hashCount = 0;
+ for (const rawDirective of (value ?? "").split(";").slice(0, 100)) {
+ const [rawName, ...tokens] = rawDirective.trim().split(/\s+/u);
+ const name = (rawName ?? "").toLowerCase();
+ if (!/^[a-z][a-z0-9-]{0,99}$/u.test(name)) continue;
+ const sources: ResponseMetadata["csp"]["directives"][number]["sources"] =
+ [];
+ for (const token of tokens.slice(0, 100)) {
+ const lower = token.toLowerCase();
+ if (lower.startsWith("'nonce-")) {
+ nonceCount += 1;
+ continue;
+ }
+ if (
+ lower.startsWith("'sha256-") ||
+ lower.startsWith("'sha384-") ||
+ lower.startsWith("'sha512-")
+ ) {
+ hashCount += 1;
+ continue;
+ }
+ sources.push(cspSource(token, baseUrl, allowedOrigins));
+ }
+ directives.push({ name, sources });
+ }
+ return { directives, nonce_count: nonceCount, hash_count: hashCount };
+};
+
+const cspSource = (
+ token: string,
+ baseUrl: string,
+ allowedOrigins: ReadonlySet,
+): ResponseMetadata["csp"]["directives"][number]["sources"][number] => {
+ const lower = token.toLowerCase();
+ if (/^'[a-z0-9-]+'$/u.test(lower))
+ return { kind: "keyword", value: lower.slice(0, 100) };
+ if (/^[a-z][a-z0-9+.-]*:$/u.test(lower))
+ return { kind: "scheme", value: lower.slice(0, 100) };
+ try {
+ const parsed = new URL(token, baseUrl);
+ return allowedOrigins.has(parsed.origin)
+ ? { kind: "approved_origin", value: parsed.origin }
+ : { kind: "external_origin", value: null };
+ } catch {
+ return { kind: "other", value: null };
+ }
+};
+
+const parseLinks = (
+ value: string | undefined,
+ baseUrl: string,
+ allowedOrigins: ReadonlySet,
+): LinkMetadata[] => {
+ const links: LinkMetadata[] = [];
+ for (const entry of splitLinkHeader(value ?? "").slice(0, 100)) {
+ const match = /^\s*<([^>]{1,4096})>(.*)$/u.exec(entry);
+ if (match === null) continue;
+ const parameters = linkParameters(match[2] ?? "");
+ const destination = safeDestination(
+ match[1] ?? "",
+ baseUrl,
+ allowedOrigins,
+ );
+ links.push({
+ href: destination.url,
+ destination_scope: destination.scope,
+ rel: (parameters.get("rel") ?? "")
+ .toLowerCase()
+ .split(/\s+/u)
+ .filter(Boolean)
+ .slice(0, 32),
+ as: boundedHeader(parameters.get("as")),
+ type: boundedHeader(parameters.get("type")),
+ crossorigin: boundedHeader(parameters.get("crossorigin")),
+ });
+ }
+ return links;
+};
+
+const splitLinkHeader = (value: string): string[] => {
+ const entries: string[] = [];
+ let start = 0;
+ let quoted = false;
+ for (let index = 0; index < value.length; index += 1) {
+ const character = value[index];
+ if (character === '"' && value[index - 1] !== "\\") quoted = !quoted;
+ if (character !== "," || quoted) continue;
+ entries.push(value.slice(start, index));
+ start = index + 1;
+ }
+ entries.push(value.slice(start));
+ return entries;
+};
+
+const linkParameters = (value: string): ReadonlyMap => {
+ const parameters = new Map();
+ for (const raw of value.split(";").slice(1, 50)) {
+ const separator = raw.indexOf("=");
+ const name = (separator < 0 ? raw : raw.slice(0, separator))
+ .trim()
+ .toLowerCase();
+ if (!/^[a-z][a-z0-9-]{0,99}$/u.test(name)) continue;
+ const parameter = separator < 0 ? "" : raw.slice(separator + 1).trim();
+ parameters.set(name, unquote(parameter).slice(0, 1_024));
+ }
+ return parameters;
+};
+
+const safeDestination = (
+ value: string,
+ baseUrl: string,
+ allowedOrigins: ReadonlySet,
+): {
+ readonly url: string | null;
+ readonly scope: LinkMetadata["destination_scope"];
+} => {
+ try {
+ const parsed = new URL(value, baseUrl);
+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+ return { url: null, scope: "unsupported" };
+ if (!allowedOrigins.has(parsed.origin))
+ return { url: null, scope: "outside_policy" };
+ return { url: sanitizeBrowserUrl(parsed.href).url, scope: "approved" };
+ } catch {
+ return { url: null, scope: "unsupported" };
+ }
+};
+
+const permissionFeatures = (value: string | undefined): string[] =>
+ [
+ ...new Set(
+ (value ?? "")
+ .split(",")
+ .map((entry) => entry.split("=", 1)[0]?.trim().toLowerCase() ?? "")
+ .filter((feature) => /^[a-z][a-z0-9-]{0,99}$/u.test(feature)),
+ ),
+ ]
+ .sort()
+ .slice(0, 200);
+
+const wellKnownHint = (url: string): AgentHint[] => {
+ try {
+ const path = new URL(url).pathname.toLowerCase();
+ return wellKnownAgentPaths.has(path)
+ ? [agentHint("well_known_resource", path, sanitizeBrowserUrl(url).url)]
+ : [];
+ } catch {
+ return [];
+ }
+};
+
+const agentHint = (
+ mechanism: AgentHint["mechanism"],
+ declaration: string,
+ url: string | null,
+): AgentHint => ({
+ mechanism,
+ declaration: declaration.slice(0, 256),
+ url,
+ trust: "page-declared-untrusted",
+});
+
+const isAgentRel = (value: string): boolean =>
+ ["mcp", "model-context", "ai-plugin", "service-desc"].includes(value);
+
+const policyToken = (value: string | undefined): string | null => {
+ const token = (value ?? "").trim().toLowerCase();
+ return /^[a-z][a-z0-9_.-]{0,99}$/u.test(token) ? token : null;
+};
+
+const nonnegativeInteger = (value: string | undefined): number | null => {
+ const number = numberValue(value === undefined ? undefined : Number(value));
+ return number === undefined ? null : Math.max(0, Math.trunc(number));
+};
+
+const boundedHeader = (value: string | undefined): string | null =>
+ value === undefined ? null : value.trim().toLowerCase().slice(0, 256);
+
+const unquote = (value: string): string =>
+ value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+
+const agentHeaderNames = ["x-model-context", "x-webmcp", "mcp-server"] as const;
+const wellKnownAgentPaths: ReadonlySet = new Set([
+ "/.well-known/ai-plugin.json",
+ "/.well-known/mcp",
+ "/.well-known/model-context",
+]);
diff --git a/src/browser/CdpScreenshot.ts b/src/browser/CdpScreenshot.ts
new file mode 100644
index 000000000..6c27518e9
--- /dev/null
+++ b/src/browser/CdpScreenshot.ts
@@ -0,0 +1,164 @@
+import type { ProgressReporter } from "../application/ProgressReporter.js";
+import type {
+ CaptureWebScreenshotInput,
+ WebScreenshot,
+} from "../domain/webScreenshot.js";
+import { createWebScreenshotArtifact } from "../domain/webScreenshot.js";
+import { BrowserObservationError } from "../domain/errors.js";
+import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js";
+import type { CdpConnection, CdpEvent } from "./CdpConnection.js";
+import {
+ allowedSanitizedUrl,
+ recordValue,
+ stringValue,
+} from "./CdpCaptureValues.js";
+import { mainFrameUrl } from "./CdpCaptureDocuments.js";
+import { captureFrames } from "./CdpCaptureDocuments.js";
+import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
+import { decodeCanonicalBase64 } from "../domain/webScreenshot.js";
+
+interface ScreenshotContext {
+ readonly connection: CdpConnection;
+ readonly sessionId: string;
+ readonly discovery: CdpEndpointDiscovery;
+ readonly target: CdpEndpointTarget;
+ readonly input: CaptureWebScreenshotInput;
+ readonly signal?: AbortSignal;
+ readonly progress?: ProgressReporter;
+}
+
+/** Capture the current viewport without navigation, evaluation, or page mutation. */
+export const captureCdpScreenshot = async (
+ context: ScreenshotContext,
+): Promise => {
+ const origins = new Set(context.input.allowed_origins);
+ await context.progress?.report({
+ phase: "browser_observation",
+ completed: 1,
+ total: 2,
+ message: "Authorizing current screenshot frame",
+ });
+ await context.connection.send(
+ "Page.enable",
+ {},
+ context.sessionId,
+ context.signal,
+ );
+ const before = await context.connection.send(
+ "Page.getFrameTree",
+ {},
+ context.sessionId,
+ context.signal,
+ );
+ const beforeUrl = mainFrameUrl(before);
+ const authorized = allowedSanitizedUrl(beforeUrl, origins);
+ const mainFrame = captureFrames(before, origins, 1).items[0];
+ if (authorized === undefined || mainFrame === undefined)
+ throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+ const navigation = { changed: false, leftScope: false };
+ const removeListener = context.connection.onEvent((event) => {
+ if (event.sessionId !== context.sessionId) return;
+ observeScreenshotNavigation(event, mainFrame.frame_id, origins, navigation);
+ });
+ let result: ReturnType;
+ let after: unknown;
+ try {
+ result = recordValue(
+ await context.connection.send(
+ "Page.captureScreenshot",
+ { format: "png", fromSurface: true, captureBeyondViewport: false },
+ context.sessionId,
+ context.signal,
+ ),
+ );
+ after = await context.connection.send(
+ "Page.getFrameTree",
+ {},
+ context.sessionId,
+ context.signal,
+ );
+ } finally {
+ removeListener();
+ }
+ const encoded = stringValue(result?.data);
+ const bytes =
+ encoded === undefined ? undefined : decodeCanonicalBase64(encoded);
+ if (
+ bytes === undefined ||
+ bytes.byteLength > context.input.maximum_image_bytes
+ )
+ throw new BrowserObservationError("inspect_web_page", "payload_limit");
+ const dimensions = pngDimensions(bytes);
+ if (navigation.leftScope)
+ throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+ const afterUrl = mainFrameUrl(after);
+ if (
+ navigation.changed ||
+ afterUrl !== beforeUrl ||
+ allowedSanitizedUrl(afterUrl, origins) === undefined
+ )
+ throw new BrowserObservationError("inspect_web_page", "target_changed");
+ await context.progress?.report({
+ phase: "browser_observation",
+ completed: 2,
+ total: 2,
+ message: "Screenshot capture complete",
+ terminal: true,
+ });
+ return {
+ schema_version: 1,
+ browser: context.discovery.version,
+ target: {
+ target_id: context.target.id,
+ url: authorized.url,
+ origin: authorized.origin ?? "",
+ },
+ captured_at: new Date().toISOString(),
+ viewport: dimensions,
+ artifact: createWebScreenshotArtifact(bytes),
+ completeness: new CdpCaptureCompleteness().snapshot(),
+ limitations: [
+ "The screenshot contains the visible viewport and may include sensitive on-screen content; capture requires separate approval.",
+ "REA does not scroll, evaluate JavaScript, or capture beyond the current viewport.",
+ ],
+ };
+};
+
+const observeScreenshotNavigation = (
+ event: CdpEvent,
+ mainFrameId: string,
+ origins: ReadonlySet,
+ state: { changed: boolean; leftScope: boolean },
+): void => {
+ const params = recordValue(event.params);
+ if (params === undefined) return;
+ const frame =
+ event.method === "Page.frameNavigated" ? recordValue(params.frame) : params;
+ if (
+ (event.method !== "Page.frameNavigated" &&
+ event.method !== "Page.navigatedWithinDocument") ||
+ (stringValue(frame?.id) ?? stringValue(frame?.frameId)) !== mainFrameId
+ )
+ return;
+ state.changed = true;
+ if (allowedSanitizedUrl(frame?.url, origins) === undefined)
+ state.leftScope = true;
+};
+
+const pngDimensions = (
+ bytes: Buffer,
+): { readonly width: number; readonly height: number } => {
+ if (
+ bytes.byteLength < 24 ||
+ !bytes.subarray(0, 8).equals(PNG_SIGNATURE) ||
+ bytes.subarray(12, 16).toString("ascii") !== "IHDR"
+ )
+ throw new BrowserObservationError("inspect_web_page", "protocol_error");
+ const width = bytes.readUInt32BE(16);
+ const height = bytes.readUInt32BE(20);
+ if (width === 0 || height === 0 || width * height > 32_000_000)
+ throw new BrowserObservationError("inspect_web_page", "payload_limit");
+ return { width, height };
+};
+
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
diff --git a/src/browser/CdpWebMcpDiscovery.ts b/src/browser/CdpWebMcpDiscovery.ts
new file mode 100644
index 000000000..8297a8a85
--- /dev/null
+++ b/src/browser/CdpWebMcpDiscovery.ts
@@ -0,0 +1,373 @@
+import { createHash } from "node:crypto";
+
+import type { ProgressReporter } from "../application/ProgressReporter.js";
+import type {
+ DiscoverWebMcpToolsInput,
+ WebMcpDiscovery,
+} from "../domain/webMcpDiscovery.js";
+import { inferJsonShape } from "../domain/jsonShape.js";
+import type { CdpEndpointDiscovery, CdpEndpointTarget } from "./CdpEndpoint.js";
+import type { CdpConnection, CdpEvent } from "./CdpConnection.js";
+import { CdpCaptureCompleteness } from "./CdpCaptureCompleteness.js";
+import { BrowserObservationError } from "../domain/errors.js";
+import {
+ allowedSanitizedUrl,
+ delayWithCancellation,
+ numberValue,
+ recordValue,
+ recordsValue,
+ stringValue,
+ type UnknownRecord,
+} from "./CdpCaptureValues.js";
+import { captureFrames, mainFrameUrl } from "./CdpCaptureDocuments.js";
+import { optionalCdpCommand } from "./CdpOptionalCommand.js";
+import { boundedSensitiveText } from "./SensitiveTextCapture.js";
+
+interface DiscoveryContext {
+ readonly connection: CdpConnection;
+ readonly sessionId: string;
+ readonly discovery: CdpEndpointDiscovery;
+ readonly target: CdpEndpointTarget;
+ readonly input: DiscoverWebMcpToolsInput;
+ readonly signal?: AbortSignal;
+ readonly progress?: ProgressReporter;
+}
+
+/** Discover WebMCP registrations without evaluating or invoking page code. */
+export const discoverWebMcp = async (
+ context: DiscoveryContext,
+): Promise => {
+ const origins = new Set(context.input.allowed_origins);
+ const limitations = [
+ "Page-declared tool metadata is untrusted and is never registered or invoked by REA.",
+ "Discovery uses only WebMCP.enable and toolsAdded/toolsRemoved; WebMCP.invokeTool is never called.",
+ ];
+ const completeness = new CdpCaptureCompleteness();
+ await context.connection.send(
+ "Page.enable",
+ {},
+ context.sessionId,
+ context.signal,
+ );
+ const frameTree = await context.connection.send(
+ "Page.getFrameTree",
+ {},
+ context.sessionId,
+ context.signal,
+ );
+ const initialUrl = mainFrameUrl(frameTree);
+ if (allowedSanitizedUrl(initialUrl, origins) === undefined)
+ throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+ const frames = captureFrames(frameTree, origins, 1_000, completeness).items;
+ const frameUrls = new Map(
+ frames.map((frame) => [
+ frame.frame_id,
+ {
+ url: frame.url,
+ origin: frame.origin,
+ parentFrameId: frame.parent_frame_id,
+ },
+ ]),
+ );
+ const tools = new Map();
+ const frameScope = { origins, frames: frameUrls, tools, completeness };
+ const removeListener = context.connection.onEvent((event) => {
+ if (event.sessionId !== context.sessionId) return;
+ if (ingestFrameScopeEvent(event, frameScope)) return;
+ ingestWebMcpEvent(event, context.input, frameUrls, tools, completeness);
+ });
+ await context.progress?.report({
+ phase: "browser_observation",
+ completed: 1,
+ total: 2,
+ message: "Enabling passive WebMCP discovery",
+ });
+ try {
+ const enabled = await optionalCdpCommand(
+ context,
+ "WebMCP.enable",
+ {},
+ limitations,
+ );
+ const available = enabled !== undefined;
+ if (!available) {
+ completeness.unavailable("webmcp_tools");
+ } else
+ // CDP sends the enable response before the required toolsAdded replay.
+ await delayWithCancellation(
+ Math.max(context.input.observation_ms, 25),
+ context.signal,
+ );
+ await assertStableAuthorizedFrame(context, initialUrl, origins);
+ return result(
+ context,
+ frameTree,
+ tools,
+ completeness,
+ limitations,
+ available,
+ );
+ } finally {
+ removeListener();
+ await context.progress?.report({
+ phase: "browser_observation",
+ completed: 2,
+ total: 2,
+ message: "WebMCP discovery complete",
+ terminal: true,
+ });
+ }
+};
+
+interface FrameScopeState {
+ readonly origins: ReadonlySet;
+ readonly frames: Map;
+ readonly tools: Map;
+ readonly completeness: CdpCaptureCompleteness;
+}
+
+interface FrameScopeFrame {
+ readonly url: string;
+ readonly origin: string | null;
+ readonly parentFrameId: string | null;
+}
+
+const ingestFrameScopeEvent = (
+ event: CdpEvent,
+ state: FrameScopeState,
+): boolean => {
+ const params = recordValue(event.params);
+ if (params === undefined) return false;
+ if (event.method === "Page.frameDetached") {
+ const frameId = stringValue(params.frameId);
+ if (frameId === undefined || frameId.length > 256)
+ state.completeness.exclude("webmcp_tools", "invalid_protocol_value");
+ else removeFrame(frameId, state.frames, state.tools);
+ return true;
+ }
+ const frame =
+ event.method === "Page.frameNavigated" ? recordValue(params.frame) : params;
+ if (
+ event.method !== "Page.frameNavigated" &&
+ event.method !== "Page.navigatedWithinDocument"
+ )
+ return false;
+ const frameId = stringValue(frame?.id) ?? stringValue(frame?.frameId);
+ if (frameId === undefined || frameId.length > 256) {
+ state.completeness.exclude("webmcp_tools", "invalid_protocol_value");
+ return true;
+ }
+ const url = allowedSanitizedUrl(frame?.url, state.origins);
+ if (url === undefined || url.origin === null) {
+ removeFrame(frameId, state.frames, state.tools);
+ state.completeness.exclude("webmcp_tools", "out_of_target_scope");
+ return true;
+ }
+ state.frames.set(frameId, {
+ url: url.url,
+ origin: url.origin,
+ parentFrameId:
+ (stringValue(frame?.parentId) ??
+ state.frames.get(frameId)?.parentFrameId ??
+ "") ||
+ null,
+ });
+ return true;
+};
+
+const removeFrame = (
+ frameId: string,
+ frames: Map,
+ tools: Map,
+): void => {
+ const pending = [frameId];
+ const removed = new Set();
+ while (pending.length > 0) {
+ const current = pending.pop();
+ if (current === undefined || removed.has(current)) continue;
+ removed.add(current);
+ for (const [candidate, frame] of frames)
+ if (frame.parentFrameId === current) pending.push(candidate);
+ frames.delete(current);
+ }
+ for (const [key, tool] of tools)
+ if (removed.has(tool.frame_id)) tools.delete(key);
+};
+
+const assertStableAuthorizedFrame = async (
+ context: DiscoveryContext,
+ initialUrl: string | undefined,
+ origins: ReadonlySet,
+): Promise => {
+ const finalTree = await context.connection.send(
+ "Page.getFrameTree",
+ {},
+ context.sessionId,
+ context.signal,
+ );
+ const finalUrl = mainFrameUrl(finalTree);
+ if (allowedSanitizedUrl(finalUrl, origins) === undefined)
+ throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+ if (finalUrl !== initialUrl)
+ throw new BrowserObservationError("inspect_web_page", "target_changed");
+};
+
+const ingestWebMcpEvent = (
+ event: CdpEvent,
+ input: DiscoverWebMcpToolsInput,
+ frames: ReadonlyMap<
+ string,
+ { readonly url: string; readonly origin: string | null }
+ >,
+ tools: Map,
+ completeness: CdpCaptureCompleteness,
+): void => {
+ const params = recordValue(event.params);
+ if (params === undefined) return;
+ if (event.method === "WebMCP.toolsRemoved") {
+ for (const removed of recordsValue(params.tools)) {
+ const name = stringValue(removed.name);
+ const frameId = stringValue(removed.frameId);
+ if (name === undefined || frameId === undefined) continue;
+ for (const [key, tool] of tools)
+ if (tool.name === name && tool.frame_id === frameId) tools.delete(key);
+ }
+ return;
+ }
+ if (event.method !== "WebMCP.toolsAdded") return;
+ for (const declared of recordsValue(params.tools)) {
+ const normalized = normalizeTool(declared, input, frames, completeness);
+ if (normalized === undefined) continue;
+ if (!tools.has(normalized.tool_key) && tools.size >= input.max_tools) {
+ completeness.drop("webmcp_tools");
+ continue;
+ }
+ tools.set(normalized.tool_key, normalized);
+ }
+};
+
+const normalizeTool = (
+ value: UnknownRecord,
+ input: DiscoverWebMcpToolsInput,
+ frames: ReadonlyMap<
+ string,
+ { readonly url: string; readonly origin: string | null }
+ >,
+ completeness: CdpCaptureCompleteness,
+): WebMcpDiscovery["tools"]["items"][number] | undefined => {
+ const frameId = stringValue(value.frameId);
+ const name = stringValue(value.name);
+ const frame = frameId === undefined ? undefined : frames.get(frameId);
+ if (
+ frameId === undefined ||
+ name === undefined ||
+ frame?.origin === null ||
+ frame === undefined
+ ) {
+ completeness.exclude("webmcp_tools", "out_of_target_scope");
+ return undefined;
+ }
+ const description = boundedSensitiveText(
+ stringValue(value.description) ?? "",
+ 4_096,
+ ).text;
+ const annotations = recordValue(value.annotations);
+ return {
+ tool_key: toolKey(frame.url, name),
+ name: boundedSensitiveText(name, 512).text,
+ description,
+ frame_id: frameId.slice(0, 256),
+ frame_url: frame.url,
+ owner_origin: frame.origin,
+ declaration_kind:
+ numberValue(value.backendNodeId) === undefined
+ ? "imperative"
+ : "declarative",
+ input_schema_shape: schemaShape(value.inputSchema, input, completeness),
+ annotations: {
+ read_only: booleanOrNull(annotations?.readOnly),
+ untrusted_content: booleanOrNull(annotations?.untrustedContent),
+ autosubmit: booleanOrNull(annotations?.autosubmit),
+ },
+ registration_source: registrationSource(
+ recordValue(value.stackTrace),
+ new Set(input.allowed_origins),
+ ),
+ trust: "page-declared-untrusted",
+ };
+};
+
+const schemaShape = (
+ value: unknown,
+ input: DiscoverWebMcpToolsInput,
+ completeness: CdpCaptureCompleteness,
+) => {
+ if (recordValue(value) === undefined) return null;
+ const encoded = JSON.stringify(value);
+ const shape = inferJsonShape(encoded, {
+ maximumBytes: input.max_schema_bytes,
+ maximumNodes: input.max_schema_nodes,
+ maximumDepth: input.max_schema_depth,
+ });
+ if (shape === null || shape.truncated) completeness.truncate("webmcp_tools");
+ return shape;
+};
+
+const registrationSource = (
+ stack: UnknownRecord | undefined,
+ allowedOrigins: ReadonlySet,
+): WebMcpDiscovery["tools"]["items"][number]["registration_source"] => {
+ const frame = recordsValue(stack?.callFrames)[0];
+ const url = allowedSanitizedUrl(frame?.url, allowedOrigins);
+ return frame === undefined || url === undefined
+ ? null
+ : {
+ url: url.url,
+ line: integerOrNull(frame.lineNumber),
+ column: integerOrNull(frame.columnNumber),
+ };
+};
+
+const result = (
+ context: DiscoveryContext,
+ frameTree: unknown,
+ tools: ReadonlyMap,
+ completeness: CdpCaptureCompleteness,
+ limitations: string[],
+ available: boolean,
+): WebMcpDiscovery => {
+ const targetUrl = mainFrameUrl(frameTree) ?? context.target.url;
+ const sanitized = allowedSanitizedUrl(
+ targetUrl,
+ new Set(context.input.allowed_origins),
+ );
+ return {
+ schema_version: 1,
+ browser: context.discovery.version,
+ target: {
+ target_id: context.target.id,
+ url: sanitized?.url ?? "[unsupported-url]",
+ origin: sanitized?.origin ?? "",
+ },
+ status: available ? "available" : "unavailable",
+ tools: {
+ total: tools.size + completeness.droppedTotal,
+ items: [...tools.values()].sort((left, right) =>
+ left.tool_key.localeCompare(right.tool_key),
+ ),
+ },
+ completeness: completeness.snapshot(),
+ limitations,
+ };
+};
+
+const toolKey = (frameUrl: string, name: string): string =>
+ `webmcp_${createHash("sha256").update(`${frameUrl}\0${name}`).digest("hex")}`;
+
+const booleanOrNull = (value: unknown): boolean | null =>
+ typeof value === "boolean" ? value : null;
+
+const integerOrNull = (value: unknown): number | null => {
+ const number = numberValue(value);
+ return number === undefined ? null : Math.max(0, Math.trunc(number));
+};
diff --git a/src/browser/ElectronFileScope.ts b/src/browser/ElectronFileScope.ts
new file mode 100644
index 000000000..42939ddbc
--- /dev/null
+++ b/src/browser/ElectronFileScope.ts
@@ -0,0 +1,56 @@
+import { realpath } from "node:fs/promises";
+import { isAbsolute, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Canonicalize operator roots before evaluating any Electron file target. */
+export const canonicalElectronRoots = async (
+ roots: readonly string[],
+): Promise => {
+ const canonical: string[] = [];
+ for (const root of roots) canonical.push(await realpath(root));
+ return [...new Set(canonical)].sort();
+};
+
+/** Resolve one file URL and reject host, encoding, and symlink root escapes. */
+export const authorizedElectronFile = async (
+ value: string,
+ roots: readonly string[],
+): Promise => {
+ if (value.length > 65_536 || /%(?:2f|5c)/iu.test(value)) return undefined;
+ let url: URL;
+ try {
+ url = new URL(value);
+ } catch {
+ return undefined;
+ }
+ if (
+ url.protocol !== "file:" ||
+ url.hostname !== "" ||
+ url.username !== "" ||
+ url.password !== ""
+ )
+ return undefined;
+ let path: string;
+ try {
+ path = fileURLToPath(url);
+ } catch {
+ return undefined;
+ }
+ if (!isAbsolute(path) || path.includes("\0")) return undefined;
+ let canonical: string;
+ try {
+ canonical = await realpath(path);
+ } catch {
+ return undefined;
+ }
+ return roots.some((root) => withinRoot(root, canonical))
+ ? canonical
+ : undefined;
+};
+
+const withinRoot = (root: string, path: string): boolean => {
+ const remainder = relative(root, path);
+ return (
+ remainder === "" || (!remainder.startsWith("..") && !isAbsolute(remainder))
+ );
+};
diff --git a/src/browser/PngVisualDiff.ts b/src/browser/PngVisualDiff.ts
new file mode 100644
index 000000000..40494071b
--- /dev/null
+++ b/src/browser/PngVisualDiff.ts
@@ -0,0 +1,222 @@
+import { inflateSync } from "node:zlib";
+
+import type {
+ CompareWebScreenshotsInput,
+ WebScreenshotArtifact,
+ WebScreenshotDiff,
+} from "../domain/webScreenshot.js";
+import { decodeCanonicalBase64 } from "../domain/webScreenshot.js";
+
+interface DecodedPng {
+ readonly width: number;
+ readonly height: number;
+ readonly rgba: Buffer;
+}
+
+/** Compare two validated screenshots using bounded, deterministic RGBA metrics. */
+export const comparePngScreenshots = (
+ input: CompareWebScreenshotsInput,
+): WebScreenshotDiff => {
+ const before = decodePng(input.before, input.maximum_pixels);
+ const after = decodePng(input.after, input.maximum_pixels);
+ if (before.width !== after.width || before.height !== after.height)
+ return {
+ schema_version: 1,
+ status: "dimension_mismatch",
+ before: dimensions(before),
+ after: dimensions(after),
+ channel_threshold: input.channel_threshold,
+ compared_pixels: 0,
+ changed_pixels: null,
+ changed_ratio: null,
+ maximum_channel_delta: null,
+ mean_absolute_channel_delta: null,
+ limitations: limitations(),
+ };
+ let changedPixels = 0;
+ let maximumDelta = 0;
+ let totalDelta = 0;
+ for (let offset = 0; offset < before.rgba.length; offset += 4) {
+ let changed = false;
+ for (let channel = 0; channel < 4; channel += 1) {
+ const delta = Math.abs(
+ (before.rgba[offset + channel] ?? 0) -
+ (after.rgba[offset + channel] ?? 0),
+ );
+ totalDelta += delta;
+ maximumDelta = Math.max(maximumDelta, delta);
+ if (delta > input.channel_threshold) changed = true;
+ }
+ if (changed) changedPixels += 1;
+ }
+ const pixels = before.width * before.height;
+ return {
+ schema_version: 1,
+ status: changedPixels === 0 ? "identical" : "different",
+ before: dimensions(before),
+ after: dimensions(after),
+ channel_threshold: input.channel_threshold,
+ compared_pixels: pixels,
+ changed_pixels: changedPixels,
+ changed_ratio: changedPixels / pixels,
+ maximum_channel_delta: maximumDelta,
+ mean_absolute_channel_delta: totalDelta / (pixels * 4),
+ limitations: limitations(),
+ };
+};
+
+const decodePng = (
+ artifact: WebScreenshotArtifact,
+ maximumPixels: number,
+): DecodedPng => {
+ const bytes = decodeCanonicalBase64(artifact.data_base64);
+ if (bytes === undefined || !bytes.subarray(0, 8).equals(PNG_SIGNATURE))
+ throw new TypeError("Invalid PNG signature");
+ let offset = 8;
+ let header: ReturnType | undefined;
+ const compressed: Buffer[] = [];
+ let sawEnd = false;
+ while (offset < bytes.length) {
+ if (offset + 12 > bytes.length) throw new TypeError("Truncated PNG chunk");
+ const length = bytes.readUInt32BE(offset);
+ const type = bytes.subarray(offset + 4, offset + 8).toString("ascii");
+ const dataStart = offset + 8;
+ const dataEnd = dataStart + length;
+ if (dataEnd + 4 > bytes.length) throw new TypeError("Truncated PNG data");
+ const data = bytes.subarray(dataStart, dataEnd);
+ if (type === "IHDR") header = parseHeader(data, maximumPixels);
+ else if (type === "IDAT") compressed.push(data);
+ else if (type === "IEND") {
+ sawEnd = true;
+ break;
+ }
+ offset = dataEnd + 4;
+ }
+ if (header === undefined || !sawEnd || compressed.length === 0)
+ throw new TypeError("Incomplete PNG");
+ const rowBytes = header.width * header.channels;
+ const expected = (rowBytes + 1) * header.height;
+ const raw = inflateSync(Buffer.concat(compressed), {
+ maxOutputLength: expected + 1,
+ });
+ if (raw.byteLength !== expected) throw new TypeError("Unexpected PNG size");
+ return {
+ width: header.width,
+ height: header.height,
+ rgba: unfilter(raw, header.width, header.height, header.channels),
+ };
+};
+
+const parseHeader = (data: Buffer, maximumPixels: number) => {
+ if (data.byteLength !== 13) throw new TypeError("Invalid PNG header");
+ const width = data.readUInt32BE(0);
+ const height = data.readUInt32BE(4);
+ const bitDepth = data[8];
+ const colorType = data[9];
+ if (
+ width === 0 ||
+ height === 0 ||
+ width * height > maximumPixels ||
+ bitDepth !== 8 ||
+ (colorType !== 2 && colorType !== 6) ||
+ data[10] !== 0 ||
+ data[11] !== 0 ||
+ data[12] !== 0
+ )
+ throw new TypeError("Unsupported or oversized PNG");
+ return { width, height, channels: colorType === 6 ? 4 : 3 };
+};
+
+const unfilter = (
+ raw: Buffer,
+ width: number,
+ height: number,
+ channels: number,
+): Buffer => {
+ const rowBytes = width * channels;
+ const decoded = Buffer.alloc(rowBytes * height);
+ for (let row = 0; row < height; row += 1) {
+ const rawOffset = row * (rowBytes + 1);
+ const outputOffset = row * rowBytes;
+ const filter = raw[rawOffset];
+ if (filter === undefined || filter > 4)
+ throw new TypeError("Unsupported PNG filter");
+ for (let column = 0; column < rowBytes; column += 1) {
+ const source = raw[rawOffset + 1 + column] ?? 0;
+ const left =
+ column >= channels
+ ? (decoded[outputOffset + column - channels] ?? 0)
+ : 0;
+ const above =
+ row > 0 ? (decoded[outputOffset + column - rowBytes] ?? 0) : 0;
+ const upperLeft =
+ row > 0 && column >= channels
+ ? (decoded[outputOffset + column - rowBytes - channels] ?? 0)
+ : 0;
+ decoded[outputOffset + column] = applyFilter(
+ filter,
+ source,
+ left,
+ above,
+ upperLeft,
+ );
+ }
+ }
+ if (channels === 4) return decoded;
+ const rgba = Buffer.alloc(width * height * 4);
+ for (
+ let source = 0, target = 0;
+ source < decoded.length;
+ source += 3, target += 4
+ ) {
+ rgba[target] = decoded[source] ?? 0;
+ rgba[target + 1] = decoded[source + 1] ?? 0;
+ rgba[target + 2] = decoded[source + 2] ?? 0;
+ rgba[target + 3] = 255;
+ }
+ return rgba;
+};
+
+const applyFilter = (
+ filter: number,
+ source: number,
+ left: number,
+ above: number,
+ upperLeft: number,
+): number => {
+ switch (filter) {
+ case 0:
+ return source;
+ case 1:
+ return (source + left) & 0xff;
+ case 2:
+ return (source + above) & 0xff;
+ case 3:
+ return (source + Math.floor((left + above) / 2)) & 0xff;
+ case 4:
+ return (source + paeth(left, above, upperLeft)) & 0xff;
+ default:
+ throw new TypeError("Unsupported PNG filter");
+ }
+};
+
+const paeth = (left: number, above: number, upperLeft: number): number => {
+ const prediction = left + above - upperLeft;
+ const leftDistance = Math.abs(prediction - left);
+ const aboveDistance = Math.abs(prediction - above);
+ const upperLeftDistance = Math.abs(prediction - upperLeft);
+ return leftDistance <= aboveDistance && leftDistance <= upperLeftDistance
+ ? left
+ : aboveDistance <= upperLeftDistance
+ ? above
+ : upperLeft;
+};
+
+const dimensions = ({ width, height }: DecodedPng) => ({ width, height });
+
+const limitations = (): string[] => [
+ "Pixel comparison does not perform OCR, semantic layout analysis, or perceptual color correction.",
+ "Only non-interlaced 8-bit RGB and RGBA PNG screenshots are accepted.",
+];
+
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
diff --git a/src/browser/SensitiveTextCapture.ts b/src/browser/SensitiveTextCapture.ts
new file mode 100644
index 000000000..b302157c3
--- /dev/null
+++ b/src/browser/SensitiveTextCapture.ts
@@ -0,0 +1,35 @@
+const SECRET_ASSIGNMENT =
+ /\b(authorization|api[_-]?key|access[_-]?token|refresh[_-]?token|password|passwd|secret|cookie|session)\b\s*[:=]\s*(?:Bearer\s+[A-Za-z0-9._~+/=-]+|"[^"]*"|'[^']*'|[^\s,;]+)/giu;
+const BEARER = /\bBearer\s+[A-Za-z0-9._~+/=-]+/giu;
+const JWT = /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/gu;
+
+/** Redact credential-shaped substrings before approved console text is retained. */
+export const redactSensitiveText = (value: string): string =>
+ value
+ .replace(SECRET_ASSIGNMENT, (_match, name: string) => `${name}=[REDACTED]`)
+ .replace(BEARER, "Bearer [REDACTED]")
+ .replace(JWT, "[REDACTED_JWT]");
+
+/** Return a UTF-8-bounded prefix without splitting a code point. */
+export const boundedSensitiveText = (
+ value: string,
+ maximumBytes: number,
+): {
+ readonly text: string;
+ readonly bytes: number;
+ readonly truncated: boolean;
+} => {
+ const redacted = redactSensitiveText(value);
+ const total = Buffer.byteLength(redacted);
+ if (total <= maximumBytes)
+ return { text: redacted, bytes: total, truncated: false };
+ let text = "";
+ let bytes = 0;
+ for (const character of redacted) {
+ const size = Buffer.byteLength(character);
+ if (bytes + size > maximumBytes) break;
+ text += character;
+ bytes += size;
+ }
+ return { text, bytes, truncated: true };
+};
diff --git a/src/browser/WebSourceMapFetcher.ts b/src/browser/WebSourceMapFetcher.ts
new file mode 100644
index 000000000..e0a532bbd
--- /dev/null
+++ b/src/browser/WebSourceMapFetcher.ts
@@ -0,0 +1,445 @@
+import { AnyMap, eachMapping } from "@jridgewell/trace-mapping";
+
+import { sanitizeBrowserUrl } from "../domain/browserObservation.js";
+import type {
+ AnalyzeWebBundleInput,
+ WebBundleAnalysis,
+} from "../domain/webBundleAnalysis.js";
+import { createWebTextArtifact } from "../domain/webContentArtifact.js";
+
+export interface WebSourceMapRequest {
+ readonly scriptKey: string;
+ readonly declaredUrl: string;
+ readonly fetchUrl: string;
+}
+
+interface SourceMapFetchHost {
+ readonly fetch: typeof fetch;
+}
+
+type SourceMaps = WebBundleAnalysis["observations"]["source_maps"];
+type SourceMapItem = SourceMaps["items"][number];
+
+/** Fetch and validate approved source maps without browser credentials. */
+export const fetchWebSourceMaps = async (
+ requests: readonly WebSourceMapRequest[],
+ input: AnalyzeWebBundleInput,
+ signal?: AbortSignal,
+ host: SourceMapFetchHost = { fetch: globalThis.fetch },
+): Promise => {
+ const items: SourceMapItem[] = [];
+ let remainingBytes = input.analysis_limits.max_total_source_map_bytes;
+ for (const request of requests.slice(
+ 0,
+ input.analysis_limits.max_source_maps,
+ )) {
+ if (signal?.aborted === true) throw signal.reason;
+ if (remainingBytes === 0) break;
+ const fetched = await fetchOne(request, {
+ input,
+ maximumBytes: Math.min(
+ input.analysis_limits.max_source_map_bytes,
+ remainingBytes,
+ ),
+ signal,
+ host,
+ });
+ items.push(fetched.item);
+ remainingBytes = Math.max(0, remainingBytes - fetched.bytesRead);
+ }
+ const included = items.filter(({ status }) => status === "included").length;
+ const dropped = requests.length - items.length;
+ const truncated =
+ dropped > 0 || items.some(({ status }) => status === "truncated");
+ return {
+ status: truncated
+ ? "truncated"
+ : items.length === 0
+ ? "unavailable"
+ : included === items.length
+ ? "included"
+ : included > 0
+ ? "partial"
+ : "unavailable",
+ requested: requests.length,
+ processed: items.length,
+ dropped,
+ dropped_script_keys: requests
+ .slice(items.length)
+ .map(({ scriptKey }) => scriptKey),
+ items,
+ };
+};
+
+interface SourceMapFetchResult {
+ readonly item: SourceMapItem;
+ readonly bytesRead: number;
+}
+
+interface SourceMapFetchContext {
+ readonly input: AnalyzeWebBundleInput;
+ readonly maximumBytes: number;
+ readonly signal: AbortSignal | undefined;
+ readonly host: SourceMapFetchHost;
+}
+
+const fetchOne = async (
+ request: WebSourceMapRequest,
+ context: SourceMapFetchContext,
+): Promise => {
+ const { input, maximumBytes, signal, host } = context;
+ const base = emptyItem(request);
+ if (!approvedUrl(request.fetchUrl, input.allowed_origins))
+ return {
+ item: {
+ ...base,
+ status: "policy_filtered",
+ limitation:
+ "Declared source-map URL is outside the approved exact origins.",
+ },
+ bytesRead: 0,
+ };
+ try {
+ const response = await fetchFollowingApprovedRedirects(
+ request.fetchUrl,
+ input.allowed_origins,
+ signal,
+ host,
+ );
+ if (response === undefined)
+ return {
+ item: {
+ ...base,
+ status: "policy_filtered",
+ limitation: "A source-map redirect left the approved exact origins.",
+ },
+ bytesRead: 0,
+ };
+ if (!response.ok)
+ return {
+ item: {
+ ...base,
+ status: "fetch_failed",
+ limitation: `Source-map server returned HTTP ${String(response.status)}.`,
+ },
+ bytesRead: 0,
+ };
+ const body = await boundedResponseText(response, maximumBytes);
+ return {
+ item: normalizeSourceMap(request, body.text, input),
+ bytesRead: body.bytes,
+ };
+ } catch (cause: unknown) {
+ if (signal?.aborted === true) throw cause;
+ return {
+ item: {
+ ...base,
+ status: isLimitError(cause) ? "truncated" : "fetch_failed",
+ limitation: isLimitError(cause)
+ ? "Source-map response exceeded the remaining approved byte budget."
+ : "Source-map fetch or validation failed.",
+ },
+ bytesRead: cause instanceof SourceMapByteLimitError ? cause.bytesRead : 0,
+ };
+ }
+};
+
+const fetchFollowingApprovedRedirects = async (
+ initialUrl: string,
+ allowedOrigins: readonly string[],
+ signal: AbortSignal | undefined,
+ host: SourceMapFetchHost,
+): Promise => {
+ let current = initialUrl;
+ for (let redirect = 0; redirect <= 5; redirect += 1) {
+ if (!approvedUrl(current, allowedOrigins)) return undefined;
+ const response = await timedFetch(current, signal, host);
+ if (response.status < 300 || response.status >= 400) return response;
+ const location = response.headers.get("location");
+ if (location === null) return response;
+ current = new URL(location, current).href;
+ }
+ throw new Error("source_map_redirect_limit");
+};
+
+const timedFetch = async (
+ url: string,
+ signal: AbortSignal | undefined,
+ host: SourceMapFetchHost,
+): Promise => {
+ const timeout = AbortSignal.timeout(5_000);
+ return await host.fetch(url, {
+ method: "GET",
+ headers: { Accept: "application/json, application/source-map+json;q=0.9" },
+ redirect: "manual",
+ credentials: "omit",
+ referrerPolicy: "no-referrer",
+ signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
+ });
+};
+
+const boundedResponseText = async (
+ response: Response,
+ maximumBytes: number,
+): Promise<{ readonly text: string; readonly bytes: number }> => {
+ const declared = Number(response.headers.get("content-length"));
+ if (Number.isFinite(declared) && declared > maximumBytes)
+ throw new SourceMapByteLimitError(0);
+ if (response.body === null) return { text: "", bytes: 0 };
+ const reader = response.body.getReader();
+ const decoder = new TextDecoder("utf-8", { fatal: true });
+ let bytes = 0;
+ let text = "";
+ for (;;) {
+ const chunk = await reader.read();
+ if (chunk.done) break;
+ bytes += chunk.value.byteLength;
+ if (bytes > maximumBytes) {
+ await reader.cancel();
+ throw new SourceMapByteLimitError(bytes);
+ }
+ text += decoder.decode(chunk.value, { stream: true });
+ }
+ text += decoder.decode();
+ return { text, bytes };
+};
+
+class SourceMapByteLimitError extends RangeError {
+ constructor(readonly bytesRead: number) {
+ super("source_map_bytes");
+ }
+}
+
+const normalizeSourceMap = (
+ request: WebSourceMapRequest,
+ text: string,
+ input: AnalyzeWebBundleInput,
+): SourceMapItem => {
+ const base = emptyItem(request);
+ if (!validSourceMapEnvelope(text))
+ return {
+ ...base,
+ status: "invalid",
+ limitation: "Source-map JSON is not a bounded version 3 map.",
+ };
+ try {
+ const map = new AnyMap(text, request.fetchUrl);
+ if (map.sources.length > input.analysis_limits.max_original_sources)
+ return {
+ ...base,
+ status: "truncated",
+ limitation: "Source map exceeds the original-source inventory limit.",
+ };
+ const resolvedBySource = new Map();
+ const originalSources = map.sources.map((source, index) => {
+ const content = map.sourcesContent?.[index];
+ const resolved =
+ map.resolvedSources[index] ?? source ?? "[unknown-source]";
+ if (source !== null) resolvedBySource.set(source, resolved);
+ return {
+ source: sanitizeSource(resolved),
+ artifact:
+ typeof content === "string"
+ ? createWebTextArtifact(content, sourceMediaType(source))
+ : null,
+ };
+ });
+ const mappings: SourceMapItem["mappings"] = [];
+ let totalMappings = 0;
+ eachMapping(map, (mapping) => {
+ if (
+ mapping.source === null ||
+ mapping.originalLine === null ||
+ mapping.originalColumn === null
+ )
+ return;
+ totalMappings += 1;
+ if (mappings.length >= input.analysis_limits.max_source_map_mappings)
+ return;
+ mappings.push({
+ generated_line: mapping.generatedLine,
+ generated_column: mapping.generatedColumn,
+ source: sanitizeSource(
+ resolvedBySource.get(mapping.source) ?? mapping.source,
+ ),
+ original_line: mapping.originalLine,
+ original_column: mapping.originalColumn,
+ name: mapping.name?.slice(0, 1_024) ?? null,
+ });
+ });
+ const modules = originalModuleEdges(
+ originalSources,
+ input.analysis_limits.max_findings,
+ );
+ const mappingTruncated = totalMappings > mappings.length;
+ const limitations = [
+ ...(mappingTruncated
+ ? [
+ `Mappings were truncated from ${String(totalMappings)} to ${String(mappings.length)}.`,
+ ]
+ : []),
+ ...(modules.truncated
+ ? [
+ `Original module edges were truncated to ${String(modules.edges.length)}.`,
+ ]
+ : []),
+ ];
+ return {
+ ...base,
+ status: mappingTruncated || modules.truncated ? "truncated" : "included",
+ artifact: createWebTextArtifact(text, "application/source-map+json"),
+ original_sources: originalSources,
+ original_module_edges: modules.edges,
+ mappings,
+ limitation: limitations.length === 0 ? null : limitations.join(" "),
+ };
+ } catch {
+ return {
+ ...base,
+ status: "invalid",
+ limitation: "Source-map mappings could not be decoded safely.",
+ };
+ }
+};
+
+const originalModuleEdges = (
+ sources: SourceMapItem["original_sources"],
+ maximum: number,
+): {
+ readonly edges: SourceMapItem["original_module_edges"];
+ readonly truncated: boolean;
+} => {
+ const edges: SourceMapItem["original_module_edges"] = [];
+ const seen = new Set();
+ for (const source of sources) {
+ if (source.artifact === null) continue;
+ for (const detector of originalImportDetectors) {
+ for (const match of source.artifact.text.matchAll(detector.pattern)) {
+ const specifier = match[1]?.slice(0, 4_096);
+ if (specifier === undefined) continue;
+ const key = `${source.source}\0${detector.kind}\0${specifier}`;
+ if (seen.has(key)) continue;
+ seen.add(key);
+ if (edges.length >= maximum) return { edges, truncated: true };
+ edges.push({
+ from_source: source.source,
+ kind: detector.kind,
+ specifier,
+ resolved_source: resolveOriginalSource(specifier, source.source),
+ });
+ }
+ }
+ }
+ return { edges, truncated: false };
+};
+
+const validSourceMapEnvelope = (text: string): boolean => {
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(text);
+ } catch {
+ return false;
+ }
+ if (!isRecord(parsed) || parsed.version !== 3) return false;
+ if (typeof parsed.mappings === "string")
+ return Array.isArray(parsed.sources) && Array.isArray(parsed.names);
+ if (!Array.isArray(parsed.sections) || parsed.sections.length > 10_000)
+ return false;
+ const pending: unknown[] = [...parsed.sections];
+ let visited = 0;
+ while (pending.length > 0) {
+ const section = pending.pop();
+ if (!isRecord(section) || !isRecord(section.offset) || !("map" in section))
+ return false;
+ visited += 1;
+ if (visited > 10_000) return false;
+ const map = section.map;
+ if (!isRecord(map) || map.version !== 3) return false;
+ if (Array.isArray(map.sections)) pending.push(...map.sections);
+ else if (
+ typeof map.mappings !== "string" ||
+ !Array.isArray(map.sources) ||
+ !Array.isArray(map.names)
+ )
+ return false;
+ }
+ return true;
+};
+
+const approvedUrl = (
+ value: string,
+ allowedOrigins: readonly string[],
+): boolean => {
+ try {
+ const parsed = new URL(value);
+ return (
+ (parsed.protocol === "http:" || parsed.protocol === "https:") &&
+ parsed.username === "" &&
+ parsed.password === "" &&
+ allowedOrigins.includes(parsed.origin)
+ );
+ } catch {
+ return false;
+ }
+};
+
+const emptyItem = (request: WebSourceMapRequest): SourceMapItem => ({
+ script_key: request.scriptKey,
+ declared_url: request.declaredUrl,
+ status: "fetch_failed",
+ artifact: null,
+ original_sources: [],
+ original_module_edges: [],
+ mappings: [],
+ limitation: null,
+});
+
+const sanitizeSource = (value: string): string => {
+ const bounded = value.slice(0, 4_096);
+ try {
+ const parsed = new URL(bounded);
+ return parsed.protocol === "http:" || parsed.protocol === "https:"
+ ? sanitizeBrowserUrl(parsed.href).url
+ : `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+ } catch {
+ return bounded.split("#", 1)[0]?.split("?", 1)[0] ?? "";
+ }
+};
+
+const resolveOriginalSource = (
+ specifier: string,
+ base: string,
+): string | null => {
+ try {
+ return sanitizeSource(new URL(specifier, base).href);
+ } catch {
+ return null;
+ }
+};
+
+const sourceMediaType = (source: string | null): string =>
+ source?.endsWith(".ts") || source?.endsWith(".tsx")
+ ? "text/typescript"
+ : "text/javascript";
+
+const isRecord = (value: unknown): value is Readonly> =>
+ typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isLimitError = (value: unknown): value is RangeError =>
+ value instanceof RangeError;
+
+const originalImportDetectors = [
+ {
+ kind: "static_import" as const,
+ pattern:
+ /\b(?:import|export)\s+(?:[^'"\n]*?\s+from\s+)?["']([^"'\n]+)["']/gu,
+ },
+ {
+ kind: "dynamic_import" as const,
+ pattern: /\bimport\s*\(\s*["']([^"'\n]+)["']\s*\)/gu,
+ },
+ {
+ kind: "require" as const,
+ pattern: /\brequire\s*\(\s*["']([^"'\n]+)["']\s*\)/gu,
+ },
+] as const;
diff --git a/src/catalogIdentity.ts b/src/catalogIdentity.ts
index 3778f080b..2e5b21215 100644
--- a/src/catalogIdentity.ts
+++ b/src/catalogIdentity.ts
@@ -38,6 +38,14 @@ export const CLI_COMMAND_NAMES = [
"policy",
"list-browser-targets",
"inspect-web-page",
+ "analyze-web-bundle",
+ "observe-web-session",
+ "discover-webmcp-tools",
+ "compare-web-captures",
+ "capture-web-screenshot",
+ "compare-web-screenshots",
+ "list-electron-targets",
+ "inspect-electron-page",
] as const;
const toolCatalog = TOOL_CONTRACTS.map((contract) => ({
diff --git a/src/cli.ts b/src/cli.ts
index ba7f2ec19..a93c699f0 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -28,6 +28,8 @@ import { projectReferenceSourceImportError } from "./application/ReferenceSource
import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
import { registerPolicyCommands } from "./cliPolicyCommands.js";
import { registerBrowserCommands } from "./cliBrowserCommands.js";
+import { registerAdvancedBrowserCommands } from "./cliBrowserAdvancedCommands.js";
+import { registerElectronCommands } from "./cliElectronCommands.js";
/**
* Build the one-shot Incur CLI without starting Hopper at import time.
@@ -75,6 +77,8 @@ export const createCli = (): ReturnType => {
registerProcessCommands(cli, logger);
registerPolicyCommands(cli, logger);
registerBrowserCommands(cli, logger);
+ registerAdvancedBrowserCommands(cli, logger);
+ registerElectronCommands(cli, logger);
return cli;
};
diff --git a/src/cliBrowserAdvancedCommands.ts b/src/cliBrowserAdvancedCommands.ts
new file mode 100644
index 000000000..cb996dd23
--- /dev/null
+++ b/src/cliBrowserAdvancedCommands.ts
@@ -0,0 +1,220 @@
+import { Cli, z } from "incur";
+
+import {
+ captureWebScreenshot,
+ compareWebCaptureEvidence,
+ compareWebScreenshotEvidence,
+ discoverWebMcpTools,
+} from "./application/BrowserObservationService.js";
+import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
+import { CdpBrowserProvider } from "./browser/CdpBrowserProvider.js";
+import { logCliCommand } from "./cliLogging.js";
+import { parseConfig } from "./config.js";
+import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+import { compareWebCapturesInputSchema } from "./domain/webCaptureDiff.js";
+import { discoverWebMcpToolsInputSchema } from "./domain/webMcpDiscovery.js";
+import {
+ captureWebScreenshotInputSchema,
+ compareWebScreenshotsInputSchema,
+} from "./domain/webScreenshot.js";
+import type { JsonValue } from "./domain/jsonValue.js";
+import type { Logger } from "./logger.js";
+
+const scopeOptions = {
+ allowedOrigins: z.array(z.string().min(1)).optional(),
+ approved: z.boolean().default(false),
+};
+
+/** Register WebMCP, capture-diff, and screenshot CLI equivalents. */
+export const registerAdvancedBrowserCommands = (
+ cli: ReturnType,
+ logger: Logger,
+): void => {
+ registerWebMcp(cli, logger);
+ registerCaptureDiff(cli, logger);
+ registerScreenshot(cli, logger);
+ registerScreenshotDiff(cli, logger);
+};
+
+const registerWebMcp = (
+ cli: ReturnType,
+ logger: Logger,
+): void => {
+ cli.command("discover-webmcp-tools", {
+ description: "Passively discover page-declared WebMCP tools",
+ args: z.object({ endpoint: z.string(), targetId: z.string() }),
+ options: z.object({
+ ...scopeOptions,
+ observationMs: z.number().int().min(0).max(10_000).default(100),
+ maxTools: z.number().int().min(1).max(5_000).default(500),
+ maxSchemaBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(1_024 * 1_024)
+ .default(256 * 1_024),
+ maxSchemaNodes: z.number().int().min(1).max(100_000).default(5_000),
+ maxSchemaDepth: z.number().int().min(1).max(100).default(20),
+ }),
+ run: ({ args, options }) =>
+ logCliCommand(logger, "discover-webmcp-tools", async () => {
+ const context = await browserContext();
+ if (!context.ok) return context.error;
+ const parsed = discoverWebMcpToolsInputSchema.safeParse({
+ cdp_endpoint: args.endpoint,
+ allowed_origins:
+ options.allowedOrigins ?? context.allowedBrowserOrigins,
+ target_id: args.targetId,
+ approved: options.approved,
+ observation_ms: options.observationMs,
+ max_tools: options.maxTools,
+ max_schema_bytes: options.maxSchemaBytes,
+ max_schema_nodes: options.maxSchemaNodes,
+ max_schema_depth: options.maxSchemaDepth,
+ });
+ if (!parsed.success) return inputError("discover_webmcp_tools");
+ const result = await discoverWebMcpTools(
+ context.provider,
+ context.authority,
+ parsed.data,
+ );
+ return result.ok ? result.value : cliError(result.error);
+ }),
+ });
+};
+
+const registerCaptureDiff = (
+ cli: ReturnType,
+ logger: Logger,
+): void => {
+ cli.command("compare-web-captures", {
+ description: "Compare two normalized web capture JSON values",
+ args: z.object({ beforeJson: z.string(), afterJson: z.string() }),
+ options: z.object({
+ maxChanges: z.number().int().min(1).max(20_000).default(2_000),
+ }),
+ run: ({ args, options }) =>
+ logCliCommand(logger, "compare-web-captures", async () => {
+ const before = parseJson(args.beforeJson);
+ const after = parseJson(args.afterJson);
+ const parsed = compareWebCapturesInputSchema.safeParse({
+ before,
+ after,
+ max_changes: options.maxChanges,
+ });
+ if (!parsed.success) return inputError("compare_web_captures");
+ const result = await compareWebCaptureEvidence(
+ new CdpBrowserProvider(),
+ parsed.data,
+ );
+ return result.ok ? result.value : cliError(result.error);
+ }),
+ });
+};
+
+const registerScreenshot = (
+ cli: ReturnType,
+ logger: Logger,
+): void => {
+ cli.command("capture-web-screenshot", {
+ description: "Capture an explicitly approved visible page viewport",
+ args: z.object({ endpoint: z.string(), targetId: z.string() }),
+ options: z.object({
+ ...scopeOptions,
+ screenshotApproved: z.boolean().default(false),
+ maximumImageBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(8 * 1_024 * 1_024)
+ .default(4 * 1_024 * 1_024),
+ }),
+ run: ({ args, options }) =>
+ logCliCommand(logger, "capture-web-screenshot", async () => {
+ const context = await browserContext();
+ if (!context.ok) return context.error;
+ const parsed = captureWebScreenshotInputSchema.safeParse({
+ cdp_endpoint: args.endpoint,
+ allowed_origins:
+ options.allowedOrigins ?? context.allowedBrowserOrigins,
+ target_id: args.targetId,
+ approved: options.approved,
+ screenshot_approved: options.screenshotApproved,
+ maximum_image_bytes: options.maximumImageBytes,
+ });
+ if (!parsed.success) return inputError("capture_web_screenshot");
+ const result = await captureWebScreenshot(
+ context.provider,
+ context.authority,
+ parsed.data,
+ );
+ return result.ok ? result.value : cliError(result.error);
+ }),
+ });
+};
+
+const registerScreenshotDiff = (
+ cli: ReturnType,
+ logger: Logger,
+): void => {
+ cli.command("compare-web-screenshots", {
+ description: "Compare two self-verifying PNG artifact JSON values",
+ args: z.object({ beforeJson: z.string(), afterJson: z.string() }),
+ options: z.object({
+ channelThreshold: z.number().int().min(0).max(255).default(0),
+ maximumPixels: z
+ .number()
+ .int()
+ .min(1)
+ .max(32_000_000)
+ .default(16_000_000),
+ }),
+ run: ({ args, options }) =>
+ logCliCommand(logger, "compare-web-screenshots", async () => {
+ const parsed = compareWebScreenshotsInputSchema.safeParse({
+ before: parseJson(args.beforeJson),
+ after: parseJson(args.afterJson),
+ channel_threshold: options.channelThreshold,
+ maximum_pixels: options.maximumPixels,
+ });
+ if (!parsed.success) return inputError("compare_web_screenshots");
+ const result = await compareWebScreenshotEvidence(
+ new CdpBrowserProvider(),
+ parsed.data,
+ );
+ return result.ok ? result.value : cliError(result.error);
+ }),
+ });
+};
+
+const browserContext = async () => {
+ const config = parseConfig(process.env);
+ if (!config.ok) return { ok: false as const, error: cliError(config.error) };
+ const authority = await loadConfiguredPermissionAuthority(config.value);
+ if (!authority.ok)
+ return { ok: false as const, error: cliError(authority.error) };
+ return {
+ ok: true as const,
+ authority: authority.value,
+ provider: new CdpBrowserProvider(),
+ allowedBrowserOrigins: config.value.browserAllowedOrigins,
+ };
+};
+
+const parseJson = (value: string): unknown => {
+ try {
+ return JSON.parse(value);
+ } catch {
+ return undefined;
+ }
+};
+
+const inputError = (operation: string): JsonValue =>
+ cliError(new AnalysisInputError(operation));
+
+const cliError = (
+ error: Parameters[0],
+): JsonValue => ({
+ error: "Browser observation failed",
+ ...projectAnalysisError(error),
+});
diff --git a/src/cliBrowserCommands.ts b/src/cliBrowserCommands.ts
index b873df441..298393e10 100644
--- a/src/cliBrowserCommands.ts
+++ b/src/cliBrowserCommands.ts
@@ -1,8 +1,10 @@
import { Cli, z } from "incur";
import {
+ analyzeWebBundle,
inspectWebPage,
listBrowserTargets,
+ observeWebSession,
} from "./application/BrowserObservationService.js";
import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
import { CdpBrowserProvider } from "./browser/CdpBrowserProvider.js";
@@ -12,6 +14,8 @@ import {
inspectWebPageInputSchema,
listBrowserTargetsInputSchema,
} from "./domain/browserObservation.js";
+import { analyzeWebBundleInputSchema } from "./domain/webBundleAnalysis.js";
+import { observeWebSessionInputSchema } from "./domain/browserSession.js";
import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
import type { JsonValue } from "./domain/jsonValue.js";
import type { Logger } from "./logger.js";
@@ -33,6 +37,8 @@ export const registerBrowserCommands = (
): void => {
registerTargetList(cli, logger);
registerPageInspection(cli, logger);
+ registerBundleAnalysis(cli, logger);
+ registerObservationSession(cli, logger);
};
const registerTargetList = (
@@ -86,11 +92,30 @@ const registerPageInspection = (
options: z.object({
...browserScopeOptions,
observationMs: z.number().int().min(0).max(10_000).default(500),
+ includeAccessibilityText: z.boolean().default(false),
+ includeConsoleText: z.boolean().default(false),
+ consoleTextApproved: z.boolean().default(false),
+ includeJsonBodyShapes: z.boolean().default(false),
+ jsonBodySchemaApproved: z.boolean().default(false),
+ includeWebsocketShapes: z.boolean().default(false),
+ websocketShapeApproved: z.boolean().default(false),
includeScriptSources: z.boolean().default(false),
includeStorageKeys: z.boolean().default(false),
maxFrames: z.number().int().min(1).max(1_000).default(200),
maxDomNodes: z.number().int().min(1).max(10_000).default(2_000),
maxAxNodes: z.number().int().min(1).max(10_000).default(2_000),
+ maxAxTextFieldBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(16 * 1_024)
+ .default(1_024),
+ maxTotalAxTextBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(1_024 * 1_024)
+ .default(64 * 1_024),
maxScripts: z.number().int().min(1).max(1_000).default(200),
maxResources: z.number().int().min(1).max(10_000).default(2_000),
maxWorkers: z.number().int().min(1).max(5_000).default(500),
@@ -109,7 +134,45 @@ const registerPageInspection = (
.default(4 * 1_024 * 1_024),
maxNetworkEvents: z.number().int().min(1).max(10_000).default(1_000),
maxConsoleEvents: z.number().int().min(1).max(2_000).default(200),
+ maxConsoleTextFieldBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(16 * 1_024)
+ .default(1_024),
+ maxTotalConsoleTextBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(1_024 * 1_024)
+ .default(64 * 1_024),
+ maxJsonBodyBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(4 * 1_024 * 1_024)
+ .default(1_024 * 1_024),
+ maxTotalJsonBodyBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(16 * 1_024 * 1_024)
+ .default(4 * 1_024 * 1_024),
+ maxJsonShapeNodes: z.number().int().min(1).max(100_000).default(5_000),
+ maxJsonShapeDepth: z.number().int().min(1).max(100).default(20),
maxWebsocketEvents: z.number().int().min(1).max(5_000).default(500),
+ maxWebsocketShapeBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(1_024 * 1_024)
+ .default(64 * 1_024),
+ maxTotalWebsocketShapeBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(16 * 1_024 * 1_024)
+ .default(1_024 * 1_024),
}),
run: ({ args, options }) =>
logCliCommand(logger, "inspect-web-page", async () => {
@@ -122,12 +185,21 @@ const registerPageInspection = (
approved: options.approved,
target_id: args.targetId,
observation_ms: options.observationMs,
+ include_accessibility_text: options.includeAccessibilityText,
+ include_console_text: options.includeConsoleText,
+ console_text_approved: options.consoleTextApproved,
+ include_json_body_shapes: options.includeJsonBodyShapes,
+ json_body_schema_approved: options.jsonBodySchemaApproved,
+ include_websocket_shapes: options.includeWebsocketShapes,
+ websocket_shape_approved: options.websocketShapeApproved,
include_script_sources: options.includeScriptSources,
include_storage_keys: options.includeStorageKeys,
limits: {
max_frames: options.maxFrames,
max_dom_nodes: options.maxDomNodes,
max_ax_nodes: options.maxAxNodes,
+ max_ax_text_field_bytes: options.maxAxTextFieldBytes,
+ max_total_ax_text_bytes: options.maxTotalAxTextBytes,
max_scripts: options.maxScripts,
max_resources: options.maxResources,
max_workers: options.maxWorkers,
@@ -136,7 +208,16 @@ const registerPageInspection = (
max_total_script_source_bytes: options.maxTotalScriptSourceBytes,
max_network_events: options.maxNetworkEvents,
max_console_events: options.maxConsoleEvents,
+ max_console_text_field_bytes: options.maxConsoleTextFieldBytes,
+ max_total_console_text_bytes: options.maxTotalConsoleTextBytes,
+ max_json_body_bytes: options.maxJsonBodyBytes,
+ max_total_json_body_bytes: options.maxTotalJsonBodyBytes,
+ max_json_shape_nodes: options.maxJsonShapeNodes,
+ max_json_shape_depth: options.maxJsonShapeDepth,
max_websocket_events: options.maxWebsocketEvents,
+ max_websocket_shape_bytes: options.maxWebsocketShapeBytes,
+ max_total_websocket_shape_bytes:
+ options.maxTotalWebsocketShapeBytes,
},
});
if (!parsed.success)
@@ -151,6 +232,122 @@ const registerPageInspection = (
});
};
+const registerBundleAnalysis = (
+ cli: ReturnType,
+ logger: Logger,
+): void => {
+ cli.command("analyze-web-bundle", {
+ description: "Capture and statically analyze an approved page bundle",
+ args: z.object({
+ endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+ targetId: z.string().describe("Target ID from list-browser-targets"),
+ }),
+ options: z.object({
+ ...browserScopeOptions,
+ sourceCaptureApproved: z.boolean().default(false),
+ observationMs: z.number().int().min(0).max(10_000).default(500),
+ fetchSourceMaps: z.boolean().default(false),
+ sourceMapFetchApproved: z.boolean().default(false),
+ maxFindings: z.number().int().min(1).max(10_000).default(1_000),
+ maxAstNodes: z.number().int().min(1).max(2_000_000).default(250_000),
+ maxSourceMaps: z.number().int().min(1).max(1_000).default(100),
+ maxSourceMapBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(16 * 1_024 * 1_024)
+ .default(4 * 1_024 * 1_024),
+ maxTotalSourceMapBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(64 * 1_024 * 1_024)
+ .default(16 * 1_024 * 1_024),
+ maxSourceMapMappings: z
+ .number()
+ .int()
+ .min(1)
+ .max(100_000)
+ .default(10_000),
+ maxOriginalSources: z.number().int().min(1).max(20_000).default(2_000),
+ }),
+ run: ({ args, options }) =>
+ logCliCommand(logger, "analyze-web-bundle", async () => {
+ const context = await browserContext();
+ if (!context.ok) return context.error;
+ const parsed = analyzeWebBundleInputSchema.safeParse({
+ cdp_endpoint: args.endpoint,
+ allowed_origins:
+ options.allowedOrigins ?? context.allowedBrowserOrigins,
+ approved: options.approved,
+ target_id: args.targetId,
+ observation_ms: options.observationMs,
+ include_script_sources: true,
+ source_capture_approved: options.sourceCaptureApproved,
+ fetch_source_maps: options.fetchSourceMaps,
+ source_map_fetch_approved: options.sourceMapFetchApproved,
+ analysis_limits: {
+ max_findings: options.maxFindings,
+ max_ast_nodes: options.maxAstNodes,
+ max_source_maps: options.maxSourceMaps,
+ max_source_map_bytes: options.maxSourceMapBytes,
+ max_total_source_map_bytes: options.maxTotalSourceMapBytes,
+ max_source_map_mappings: options.maxSourceMapMappings,
+ max_original_sources: options.maxOriginalSources,
+ },
+ });
+ if (!parsed.success)
+ return cliError(new AnalysisInputError("analyze_web_bundle"));
+ const result = await analyzeWebBundle(
+ context.provider,
+ context.authority,
+ parsed.data,
+ );
+ return result.ok ? result.value : cliError(result.error);
+ }),
+ });
+};
+
+const registerObservationSession = (
+ cli: ReturnType,
+ logger: Logger,
+): void => {
+ cli.command("observe-web-session", {
+ description: "Observe user-driven page navigation during a bounded window",
+ args: z.object({
+ endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+ targetId: z.string().describe("Target ID from list-browser-targets"),
+ }),
+ options: z.object({
+ ...browserScopeOptions,
+ observationMs: z.number().int().min(1).max(60_000).default(10_000),
+ maxTimelineEvents: z.number().int().min(1).max(20_000).default(2_000),
+ }),
+ run: ({ args, options }) =>
+ logCliCommand(logger, "observe-web-session", async () => {
+ const context = await browserContext();
+ if (!context.ok) return context.error;
+ const parsed = observeWebSessionInputSchema.safeParse({
+ cdp_endpoint: args.endpoint,
+ allowed_origins:
+ options.allowedOrigins ?? context.allowedBrowserOrigins,
+ target_id: args.targetId,
+ approved: options.approved,
+ observation_ms: options.observationMs,
+ max_timeline_events: options.maxTimelineEvents,
+ });
+ if (!parsed.success)
+ return cliError(new AnalysisInputError("observe_web_session"));
+ const result = await observeWebSession(
+ context.provider,
+ context.authority,
+ parsed.data,
+ );
+ return result.ok ? result.value : cliError(result.error);
+ }),
+ });
+};
+
const browserContext = async () => {
const config = parseConfig(process.env);
if (!config.ok) return { ok: false as const, error: cliError(config.error) };
diff --git a/src/cliElectronCommands.ts b/src/cliElectronCommands.ts
new file mode 100644
index 000000000..cf6309bbe
--- /dev/null
+++ b/src/cliElectronCommands.ts
@@ -0,0 +1,141 @@
+import { Cli, z } from "incur";
+
+import {
+ inspectElectronPage,
+ listElectronTargets,
+} from "./application/ElectronObservationService.js";
+import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
+import { CdpElectronProvider } from "./browser/CdpElectronProvider.js";
+import { logCliCommand } from "./cliLogging.js";
+import { parseConfig } from "./config.js";
+import {
+ inspectElectronPageInputSchema,
+ listElectronTargetsInputSchema,
+} from "./domain/electronObservation.js";
+import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+import type { JsonValue } from "./domain/jsonValue.js";
+import type { Logger } from "./logger.js";
+
+const scopeOptions = {
+ allowedFileRoots: z
+ .array(z.string().min(1))
+ .optional()
+ .describe("Filesystem roots; defaults to REA_ELECTRON_FILE_ROOTS_JSON"),
+ approved: z.boolean().default(false),
+};
+
+/** Register CLI equivalents of the Electron MCP tools. */
+export const registerElectronCommands = (
+ cli: ReturnType,
+ logger: Logger,
+): void => {
+ cli.command("list-electron-targets", {
+ description: "List root-confined file pages from Electron CDP",
+ args: z.object({ endpoint: z.string() }),
+ options: z.object({
+ ...scopeOptions,
+ offset: z.number().int().min(0).default(0),
+ limit: z.number().int().min(1).max(200).default(100),
+ }),
+ run: ({ args, options }) =>
+ logCliCommand(logger, "list-electron-targets", async () => {
+ const context = await electronContext();
+ if (!context.ok) return context.error;
+ const parsed = listElectronTargetsInputSchema.safeParse({
+ cdp_endpoint: args.endpoint,
+ allowed_file_roots:
+ options.allowedFileRoots ?? context.allowedFileRoots,
+ approved: options.approved,
+ offset: options.offset,
+ limit: options.limit,
+ });
+ if (!parsed.success) return inputError("list_electron_targets");
+ const result = await listElectronTargets(
+ context.provider,
+ context.authority,
+ parsed.data,
+ );
+ return result.ok ? result.value : cliError(result.error);
+ }),
+ });
+ cli.command("inspect-electron-page", {
+ description: "Passively inspect one root-confined Electron file page",
+ args: z.object({ endpoint: z.string(), targetId: z.string() }),
+ options: z.object({
+ ...scopeOptions,
+ observationMs: z.number().int().min(0).max(10_000).default(100),
+ includeScriptSources: z.boolean().default(false),
+ sourceCaptureApproved: z.boolean().default(false),
+ maxFrames: z.number().int().min(1).max(1_000).default(200),
+ maxDomNodes: z.number().int().min(1).max(10_000).default(2_000),
+ maxScripts: z.number().int().min(1).max(2_000).default(500),
+ maxResources: z.number().int().min(1).max(10_000).default(2_000),
+ maxScriptSourceBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(4 * 1_024 * 1_024)
+ .default(1_024 * 1_024),
+ maxTotalScriptSourceBytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(16 * 1_024 * 1_024)
+ .default(4 * 1_024 * 1_024),
+ }),
+ run: ({ args, options }) =>
+ logCliCommand(logger, "inspect-electron-page", async () => {
+ const context = await electronContext();
+ if (!context.ok) return context.error;
+ const parsed = inspectElectronPageInputSchema.safeParse({
+ cdp_endpoint: args.endpoint,
+ allowed_file_roots:
+ options.allowedFileRoots ?? context.allowedFileRoots,
+ target_id: args.targetId,
+ approved: options.approved,
+ observation_ms: options.observationMs,
+ include_script_sources: options.includeScriptSources,
+ source_capture_approved: options.sourceCaptureApproved,
+ limits: {
+ max_frames: options.maxFrames,
+ max_dom_nodes: options.maxDomNodes,
+ max_scripts: options.maxScripts,
+ max_resources: options.maxResources,
+ max_script_source_bytes: options.maxScriptSourceBytes,
+ max_total_script_source_bytes: options.maxTotalScriptSourceBytes,
+ },
+ });
+ if (!parsed.success) return inputError("inspect_electron_page");
+ const result = await inspectElectronPage(
+ context.provider,
+ context.authority,
+ parsed.data,
+ );
+ return result.ok ? result.value : cliError(result.error);
+ }),
+ });
+};
+
+const electronContext = async () => {
+ const config = parseConfig(process.env);
+ if (!config.ok) return { ok: false as const, error: cliError(config.error) };
+ const authority = await loadConfiguredPermissionAuthority(config.value);
+ if (!authority.ok)
+ return { ok: false as const, error: cliError(authority.error) };
+ return {
+ ok: true as const,
+ authority: authority.value,
+ provider: new CdpElectronProvider(),
+ allowedFileRoots: config.value.electronFileRoots,
+ };
+};
+
+const inputError = (operation: string): JsonValue =>
+ cliError(new AnalysisInputError(operation));
+
+const cliError = (
+ error: Parameters[0],
+): JsonValue => ({
+ error: "Electron observation failed",
+ ...projectAnalysisError(error),
+});
diff --git a/src/cliPolicyCommands.ts b/src/cliPolicyCommands.ts
index 0ed60785b..d28e2abe0 100644
--- a/src/cliPolicyCommands.ts
+++ b/src/cliPolicyCommands.ts
@@ -17,6 +17,7 @@ import type { Logger } from "./logger.js";
const capabilitySchema = z.enum([
"process_capture",
"browser_observe",
+ "electron_observe",
"evidence_read",
"evidence_write",
"investigation_input",
diff --git a/src/config.ts b/src/config.ts
index d8ab4b457..109e5a6e9 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -14,6 +14,7 @@ import {
browserEndpointSchema,
browserOriginSchema,
} from "./domain/browserObservation.js";
+import { electronFileRootsSchema } from "./domain/electronObservation.js";
const DEFAULT_HOPPER_LAUNCHER_PATH =
"/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
@@ -38,6 +39,9 @@ export interface AppConfig {
readonly browserObservationEnabled: boolean;
readonly browserCdpEndpoints: readonly string[];
readonly browserAllowedOrigins: readonly string[];
+ readonly electronObservationEnabled: boolean;
+ readonly electronCdpEndpoints: readonly string[];
+ readonly electronFileRoots: readonly string[];
readonly permissionCeilings: readonly PermissionCeiling[];
readonly administratorPermissionGrants: readonly PermissionGrant[];
readonly permissionProjectRoot: string | undefined;
@@ -76,6 +80,9 @@ const environmentSchema = z
REA_BROWSER_OBSERVE_ENABLED: z.enum(["true", "false"]).default("false"),
REA_BROWSER_CDP_ENDPOINTS_JSON: z.string().default("[]"),
REA_BROWSER_ALLOWED_ORIGINS_JSON: z.string().default("[]"),
+ REA_ELECTRON_OBSERVE_ENABLED: z.enum(["true", "false"]).default("false"),
+ REA_ELECTRON_CDP_ENDPOINTS_JSON: z.string().default("[]"),
+ REA_ELECTRON_FILE_ROOTS_JSON: z.string().default("[]"),
REA_PERMISSION_PROJECT_ROOT: z.string().min(1).optional(),
REA_PERMISSION_PROJECT_STORE: z.string().min(1).optional(),
})
@@ -133,6 +140,31 @@ const parseBrowserArray = (
}
};
+const parseElectronFileRoots = (
+ encoded: string,
+): Result => {
+ try {
+ const decoded: unknown = JSON.parse(encoded);
+ if (Array.isArray(decoded) && decoded.length === 0) return ok([]);
+ const parsed = electronFileRootsSchema.safeParse(decoded);
+ return parsed.success
+ ? ok(parsed.data)
+ : err(
+ new ConfigurationError(
+ "REA_ELECTRON_FILE_ROOTS_JSON must encode absolute roots",
+ { cause: parsed.error },
+ ),
+ );
+ } catch (cause: unknown) {
+ return err(
+ new ConfigurationError(
+ "REA_ELECTRON_FILE_ROOTS_JSON must be valid JSON",
+ { cause },
+ ),
+ );
+ }
+};
+
const filePolicy = (roots: readonly string[]): EvidenceFilePolicy => ({
roots,
maxBytes: 64 * 1024 * 1024,
@@ -266,6 +298,17 @@ export const parseConfig = (
32,
);
if (!browserOrigins.ok) return browserOrigins;
+ const electronEndpoints = parseBrowserArray(
+ parsedEnvironment.data.REA_ELECTRON_CDP_ENDPOINTS_JSON,
+ "REA_ELECTRON_CDP_ENDPOINTS_JSON",
+ browserEndpointSchema,
+ 16,
+ );
+ if (!electronEndpoints.ok) return electronEndpoints;
+ const electronFileRoots = parseElectronFileRoots(
+ parsedEnvironment.data.REA_ELECTRON_FILE_ROOTS_JSON,
+ );
+ if (!electronFileRoots.ok) return electronFileRoots;
const permissionCeilings = [
...(parsedEnvironment.data.REA_PROCESS_CAPTURE_ENABLED === "true"
? [
@@ -297,6 +340,14 @@ export const parseConfig = (
}),
]
: []),
+ ...(parsedEnvironment.data.REA_ELECTRON_OBSERVE_ENABLED === "true"
+ ? [
+ permissionScope("electron_observe", electronFileRoots.value, {
+ origins: electronEndpoints.value,
+ network: "loopback",
+ }),
+ ]
+ : []),
...(parsedEnvironment.data.REA_ARTIFACT_NATIVE_MOUNT_ENABLED === "true"
? [permissionScope("native_mount", [], { mount: true })]
: []),
@@ -336,6 +387,10 @@ export const parseConfig = (
parsedEnvironment.data.REA_BROWSER_OBSERVE_ENABLED === "true",
browserCdpEndpoints: browserEndpoints.value,
browserAllowedOrigins: browserOrigins.value,
+ electronObservationEnabled:
+ parsedEnvironment.data.REA_ELECTRON_OBSERVE_ENABLED === "true",
+ electronCdpEndpoints: electronEndpoints.value,
+ electronFileRoots: electronFileRoots.value,
permissionCeilings,
administratorPermissionGrants: administratorGrants(permissionCeilings),
permissionProjectRoot: parsedEnvironment.data.REA_PERMISSION_PROJECT_ROOT,
diff --git a/src/contracts/browserToolContracts.ts b/src/contracts/browserToolContracts.ts
index 40d6592f1..2d9b883bb 100644
--- a/src/contracts/browserToolContracts.ts
+++ b/src/contracts/browserToolContracts.ts
@@ -1,4 +1,5 @@
import type { ToolContract } from "./toolContracts.js";
+import { z } from "zod";
import { evidenceSchema } from "../domain/evidence.js";
import {
browserTargetListSchema,
@@ -6,8 +7,30 @@ import {
listBrowserTargetsInputSchema,
webPageInspectionSchema,
} from "../domain/browserObservation.js";
+import {
+ analyzeWebBundleInputSchema,
+ webBundleAnalysisSchema,
+} from "../domain/webBundleAnalysis.js";
+import {
+ observeWebSessionInputSchema,
+ webObservationSessionSchema,
+} from "../domain/browserSession.js";
+import {
+ discoverWebMcpToolsInputSchema,
+ webMcpDiscoverySchema,
+} from "../domain/webMcpDiscovery.js";
+import {
+ compareWebCapturesInputSchema,
+ webCaptureDiffSchema,
+} from "../domain/webCaptureDiff.js";
+import {
+ captureWebScreenshotInputSchema,
+ compareWebScreenshotsInputSchema,
+ webScreenshotDiffSchema,
+ webScreenshotSchema,
+} from "../domain/webScreenshot.js";
-const evidenceResult = (schema: typeof browserTargetListSchema) =>
+const evidenceResult = (schema: Schema) =>
evidenceSchema
.omit({ normalized_result: true })
.extend({ normalized_result: schema });
@@ -15,6 +38,16 @@ const listOutputSchema = evidenceResult(browserTargetListSchema);
const inspectionOutputSchema = evidenceSchema
.omit({ normalized_result: true })
.extend({ normalized_result: webPageInspectionSchema });
+const bundleOutputSchema = evidenceSchema
+ .omit({ normalized_result: true })
+ .extend({ normalized_result: webBundleAnalysisSchema });
+const observationSessionOutputSchema = evidenceSchema
+ .omit({ normalized_result: true })
+ .extend({ normalized_result: webObservationSessionSchema });
+const webMcpOutputSchema = evidenceResult(webMcpDiscoverySchema);
+const captureDiffOutputSchema = evidenceResult(webCaptureDiffSchema);
+const screenshotOutputSchema = evidenceResult(webScreenshotSchema);
+const screenshotDiffOutputSchema = evidenceResult(webScreenshotDiffSchema);
const endpoint = "http://127.0.0.1:9222";
const origin = "https://app.example.test";
@@ -69,12 +102,21 @@ export const BROWSER_TOOL_CONTRACTS = [
approved: true,
target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS",
observation_ms: 500,
+ include_accessibility_text: false,
+ include_console_text: false,
+ console_text_approved: false,
+ include_json_body_shapes: false,
+ json_body_schema_approved: false,
+ include_websocket_shapes: false,
+ websocket_shape_approved: false,
include_script_sources: false,
include_storage_keys: false,
limits: {
max_frames: 200,
max_dom_nodes: 2_000,
max_ax_nodes: 2_000,
+ max_ax_text_field_bytes: 1_024,
+ max_total_ax_text_bytes: 65_536,
max_scripts: 200,
max_resources: 2_000,
max_workers: 500,
@@ -83,10 +125,296 @@ export const BROWSER_TOOL_CONTRACTS = [
max_total_script_source_bytes: 4_194_304,
max_network_events: 1_000,
max_console_events: 200,
+ max_console_text_field_bytes: 1_024,
+ max_total_console_text_bytes: 65_536,
+ max_json_body_bytes: 1_048_576,
+ max_total_json_body_bytes: 4_194_304,
+ max_json_shape_nodes: 5_000,
+ max_json_shape_depth: 20,
max_websocket_events: 500,
+ max_websocket_shape_bytes: 65_536,
+ max_total_websocket_shape_bytes: 1_048_576,
},
},
},
],
},
+ {
+ name: "analyze_web_bundle",
+ description:
+ "Capture explicitly approved JavaScript source from one approved CDP page and statically derive a bounded chunk graph, route and endpoint candidates, vendor fingerprints, page-declared WebMCP metadata, and optional separately approved source-map evidence. JavaScript is parsed but never executed.",
+ kind: "browser-provider",
+ inputSchema: analyzeWebBundleInputSchema,
+ outputSchema: bundleOutputSchema,
+ annotations: {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: true,
+ },
+ examples: [
+ {
+ title: "Analyze an approved page bundle",
+ input: {
+ cdp_endpoint: endpoint,
+ allowed_origins: [origin],
+ approved: true,
+ target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS",
+ observation_ms: 500,
+ include_accessibility_text: false,
+ include_script_sources: true,
+ include_storage_keys: false,
+ source_capture_approved: true,
+ fetch_source_maps: false,
+ source_map_fetch_approved: false,
+ analysis_limits: {
+ max_findings: 1_000,
+ max_ast_nodes: 250_000,
+ max_source_maps: 100,
+ max_source_map_bytes: 4_194_304,
+ max_total_source_map_bytes: 16_777_216,
+ max_source_map_mappings: 10_000,
+ max_original_sources: 2_000,
+ },
+ },
+ },
+ ],
+ },
+ {
+ name: "observe_web_session",
+ description:
+ "Arm a bounded CDP observation window while the user operates the page. Allows approved same-origin reload and SPA navigation, records ordered navigation, redirect, lifecycle, and failure metadata, and stops before retaining an out-of-policy destination.",
+ kind: "browser-provider",
+ inputSchema: observeWebSessionInputSchema,
+ outputSchema: observationSessionOutputSchema,
+ annotations: {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: false,
+ openWorldHint: true,
+ },
+ examples: [
+ {
+ title: "Observe one external user action",
+ input: {
+ cdp_endpoint: endpoint,
+ allowed_origins: [origin],
+ target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS",
+ approved: true,
+ observation_ms: 10_000,
+ max_timeline_events: 2_000,
+ },
+ },
+ ],
+ },
+ {
+ name: "discover_webmcp_tools",
+ description:
+ "Passively inventory page-registered WebMCP tools using the experimental CDP WebMCP domain. Metadata is bounded and page-declared-untrusted; REA never registers or invokes discovered tools.",
+ kind: "browser-provider",
+ inputSchema: discoverWebMcpToolsInputSchema,
+ outputSchema: webMcpOutputSchema,
+ annotations: {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: true,
+ },
+ examples: [
+ {
+ title: "Discover current WebMCP declarations",
+ input: {
+ cdp_endpoint: endpoint,
+ allowed_origins: [origin],
+ target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS",
+ approved: true,
+ observation_ms: 100,
+ max_tools: 500,
+ max_schema_bytes: 262_144,
+ max_schema_nodes: 5_000,
+ max_schema_depth: 20,
+ },
+ },
+ ],
+ },
+ {
+ name: "compare_web_captures",
+ description:
+ "Compare two normalized web captures across DOM, scripts, resources, network, safe metadata, and optional WebMCP inventories. Stable observed changes are distinguished from unknown absence caused by incomplete capture coverage.",
+ kind: "browser-provider",
+ inputSchema: compareWebCapturesInputSchema,
+ outputSchema: captureDiffOutputSchema,
+ annotations: {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: false,
+ },
+ examples: [
+ {
+ title: "Compare two normalized captures",
+ input: {
+ before: { inspection: exampleInspection() },
+ after: { inspection: exampleInspection() },
+ max_changes: 2_000,
+ },
+ },
+ ],
+ },
+ {
+ name: "capture_web_screenshot",
+ description:
+ "Capture the current visible viewport of one approved page as a bounded, content-addressed PNG artifact. Screenshot capture requires separate explicit approval and never scrolls, navigates, or evaluates page JavaScript.",
+ kind: "browser-provider",
+ inputSchema: captureWebScreenshotInputSchema,
+ outputSchema: screenshotOutputSchema,
+ annotations: {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: false,
+ openWorldHint: true,
+ },
+ examples: [
+ {
+ title: "Capture an approved viewport",
+ input: {
+ cdp_endpoint: endpoint,
+ allowed_origins: [origin],
+ target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS",
+ approved: true,
+ screenshot_approved: true,
+ maximum_image_bytes: 4_194_304,
+ },
+ },
+ ],
+ },
+ {
+ name: "compare_web_screenshots",
+ description:
+ "Compare two self-verifying PNG screenshot artifacts with bounded local pixel metrics. Returns exact changed-pixel ratios and channel deltas without OCR or external services.",
+ kind: "browser-provider",
+ inputSchema: compareWebScreenshotsInputSchema,
+ outputSchema: screenshotDiffOutputSchema,
+ annotations: {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: false,
+ },
+ examples: [
+ {
+ title: "Compare two screenshot artifacts",
+ input: {
+ before: exampleScreenshot(),
+ after: exampleScreenshot(),
+ channel_threshold: 0,
+ maximum_pixels: 16_000_000,
+ },
+ },
+ ],
+ },
] as const satisfies readonly ToolContract[];
+
+function exampleCompleteness() {
+ return {
+ status: "complete_within_window",
+ conditions: ["complete_within_window"],
+ policy_filtered_sections: [],
+ attach_limited_sections: [],
+ truncated_sections: [],
+ unavailable_sections: [],
+ excluded: [],
+ dropped_events: {
+ scripts: 0,
+ network_requests: 0,
+ console_events: 0,
+ websocket_connections: 0,
+ websocket_frames: 0,
+ webmcp_tools: 0,
+ timeline_events: 0,
+ total: 0,
+ },
+ };
+}
+
+function exampleInspection() {
+ return {
+ schema_version: 2,
+ browser: {
+ product: "Chrome/1",
+ protocol_version: "1.3",
+ revision: "example",
+ user_agent: "Chrome",
+ js_version: "1",
+ },
+ target: {
+ target_id: "page-1",
+ type: "page",
+ title: "Example",
+ url: `${origin}/`,
+ origin,
+ attached: false,
+ },
+ capture_window: {
+ started_at: "2026-07-14T00:00:00.000Z",
+ ended_at: "2026-07-14T00:00:01.000Z",
+ observation_ms: 1_000,
+ },
+ completeness: exampleCompleteness(),
+ frames: [],
+ dom: { total_nodes: 0, nodes: [] },
+ accessibility: {
+ total_nodes: 0,
+ text_capture: {
+ status: "not_approved",
+ retained_bytes: 0,
+ excluded_fields: 0,
+ truncated_fields: 0,
+ },
+ nodes: [],
+ },
+ scripts: { total: 0, items: [] },
+ resources: [],
+ network: {
+ requests: [],
+ websocket_events: [],
+ coverage_started_at: "2026-07-14T00:00:00.000Z",
+ prior_activity_available: false,
+ },
+ console: {
+ events: [],
+ coverage_started_at: "2026-07-14T00:00:00.000Z",
+ prior_activity_available: false,
+ },
+ workers: [],
+ metadata: {
+ responses: [],
+ dom_urls: [],
+ agent_hints: [],
+ excluded_dom_urls: 0,
+ headers_allowlisted: true,
+ },
+ storage: {
+ origin,
+ usage_bytes: null,
+ quota_bytes: null,
+ local_storage_keys: [],
+ session_storage_keys: [],
+ indexed_db_names: [],
+ cache_names: [],
+ values_redacted: true,
+ },
+ limitations: [],
+ };
+}
+
+function exampleScreenshot() {
+ return {
+ uri: "rea://web-screenshot/sha256/153cf6c9a526a63053a37b10234c2fd85df38887c2dc0a800d90abfa6631d01c",
+ sha256: "153cf6c9a526a63053a37b10234c2fd85df38887c2dc0a800d90abfa6631d01c",
+ bytes: 70,
+ media_type: "image/png",
+ data_base64:
+ "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PzWvWQAAAABJRU5ErkJggg==",
+ };
+}
diff --git a/src/contracts/electronToolContracts.ts b/src/contracts/electronToolContracts.ts
new file mode 100644
index 000000000..9184856f7
--- /dev/null
+++ b/src/contracts/electronToolContracts.ts
@@ -0,0 +1,84 @@
+import type { ToolContract } from "./toolContracts.js";
+import { evidenceSchema } from "../domain/evidence.js";
+import {
+ electronPageInspectionSchema,
+ electronTargetListSchema,
+ inspectElectronPageInputSchema,
+ listElectronTargetsInputSchema,
+} from "../domain/electronObservation.js";
+
+const listOutputSchema = evidenceSchema
+ .omit({ normalized_result: true })
+ .extend({ normalized_result: electronTargetListSchema });
+const inspectionOutputSchema = evidenceSchema
+ .omit({ normalized_result: true })
+ .extend({ normalized_result: electronPageInspectionSchema });
+
+const endpoint = "http://127.0.0.1:9223";
+const root = "/Applications/Example.app/Contents/Resources";
+
+/** Root-confined Electron file-page discovery and inspection contracts. */
+export const ELECTRON_TOOL_CONTRACTS = [
+ {
+ name: "list_electron_targets",
+ description:
+ "List Electron file:// page targets from an approved user-owned loopback CDP endpoint. Every path is canonicalized and must remain contained by an approved filesystem root, including after symlink resolution.",
+ kind: "electron-provider",
+ inputSchema: listElectronTargetsInputSchema,
+ outputSchema: listOutputSchema,
+ annotations: {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: true,
+ },
+ examples: [
+ {
+ title: "List approved Electron file pages",
+ input: {
+ cdp_endpoint: endpoint,
+ allowed_file_roots: [root],
+ approved: true,
+ offset: 0,
+ limit: 100,
+ },
+ },
+ ],
+ },
+ {
+ name: "inspect_electron_page",
+ description:
+ "Passively inspect one approved Electron file page through CDP. Returns root-confined frames, DOM structure, resource paths, and scripts without evaluating renderer JavaScript or invoking Electron APIs; script contents require separate approval.",
+ kind: "electron-provider",
+ inputSchema: inspectElectronPageInputSchema,
+ outputSchema: inspectionOutputSchema,
+ annotations: {
+ readOnlyHint: true,
+ destructiveHint: false,
+ idempotentHint: true,
+ openWorldHint: true,
+ },
+ examples: [
+ {
+ title: "Inspect an approved Electron page",
+ input: {
+ cdp_endpoint: endpoint,
+ allowed_file_roots: [root],
+ target_id: "TARGET_ID_FROM_LIST_ELECTRON_TARGETS",
+ approved: true,
+ observation_ms: 100,
+ include_script_sources: false,
+ source_capture_approved: false,
+ limits: {
+ max_frames: 200,
+ max_dom_nodes: 2_000,
+ max_scripts: 500,
+ max_resources: 2_000,
+ max_script_source_bytes: 1_048_576,
+ max_total_script_source_bytes: 4_194_304,
+ },
+ },
+ },
+ ],
+ },
+] as const satisfies readonly ToolContract[];
diff --git a/src/contracts/toolContractTypes.ts b/src/contracts/toolContractTypes.ts
index 2e8ada42c..e71312e80 100644
--- a/src/contracts/toolContractTypes.ts
+++ b/src/contracts/toolContractTypes.ts
@@ -23,6 +23,7 @@ export type ToolKind =
| "native-provider"
| "artifact-provider"
| "browser-provider"
+ | "electron-provider"
| "session";
/** Single source of truth for a public MCP tool. */
diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.ts
index 62e29b6d2..a6f3f2d43 100644
--- a/src/contracts/toolContracts.ts
+++ b/src/contracts/toolContracts.ts
@@ -27,6 +27,7 @@ import { TOOL_EXAMPLE_OVERRIDES } from "./toolContractExamples.js";
import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js";
import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";
import { BROWSER_TOOL_CONTRACTS } from "./browserToolContracts.js";
+import { ELECTRON_TOOL_CONTRACTS } from "./electronToolContracts.js";
import {
closeBinaryInputSchema,
openBinaryInputSchema,
@@ -520,5 +521,6 @@ export const TOOL_CONTRACTS = [
...NATIVE_TOOL_CONTRACTS,
...ARTIFACT_TOOL_CONTRACTS,
...BROWSER_TOOL_CONTRACTS,
+ ...ELECTRON_TOOL_CONTRACTS,
...SESSION_TOOL_CONTRACTS,
] as const;
diff --git a/src/domain/browserCompleteness.ts b/src/domain/browserCompleteness.ts
new file mode 100644
index 000000000..2fd8769df
--- /dev/null
+++ b/src/domain/browserCompleteness.ts
@@ -0,0 +1,142 @@
+import { z } from "zod";
+
+/** Stable browser sections used by coverage and omission accounting. */
+const browserSectionSchema = z.enum([
+ "frames",
+ "dom",
+ "accessibility",
+ "scripts",
+ "script_sources",
+ "resources",
+ "network_requests",
+ "network_initiators",
+ "console_events",
+ "console_text",
+ "websocket_connections",
+ "websocket_frames",
+ "websocket_shapes",
+ "json_body_shapes",
+ "workers",
+ "storage",
+ "storage_keys",
+ "metadata",
+ "webmcp_tools",
+ "screenshot",
+ "source_maps",
+ "timeline",
+]);
+export type BrowserSection = z.infer;
+
+/** Why an eligible browser observation was not retained. */
+const browserExclusionReasonSchema = z.enum([
+ "disallowed_origin",
+ "unsupported_url",
+ "unattributed_origin",
+ "not_approved",
+ "out_of_target_scope",
+ "provider_unavailable",
+ "invalid_protocol_value",
+]);
+export type BrowserExclusionReason = z.infer<
+ typeof browserExclusionReasonSchema
+>;
+
+const browserExclusionSchema = z.object({
+ section: browserSectionSchema,
+ reason: browserExclusionReasonSchema,
+ count: z.number().int().min(0).nullable(),
+});
+export type BrowserExclusion = z.infer;
+
+const browserDroppedEventsSchema = z.object({
+ scripts: z.number().int().min(0),
+ network_requests: z.number().int().min(0),
+ console_events: z.number().int().min(0),
+ websocket_connections: z.number().int().min(0),
+ websocket_frames: z.number().int().min(0),
+ webmcp_tools: z.number().int().min(0),
+ timeline_events: z.number().int().min(0),
+ total: z.number().int().min(0),
+});
+export type BrowserDroppedEvents = z.infer;
+export type BrowserDroppedEventKind = Exclude<
+ keyof BrowserDroppedEvents,
+ "total"
+>;
+
+const browserCompletenessConditionSchema = z.enum([
+ "complete_within_window",
+ "policy_filtered",
+ "attach_limited",
+ "truncated",
+]);
+
+/** Explicit, non-lossy coverage semantics for a bounded browser observation. */
+export const browserCompletenessSchema = z.object({
+ status: browserCompletenessConditionSchema,
+ conditions: z.array(browserCompletenessConditionSchema).min(1).max(3),
+ policy_filtered_sections: z.array(browserSectionSchema),
+ attach_limited_sections: z.array(browserSectionSchema),
+ truncated_sections: z.array(browserSectionSchema),
+ unavailable_sections: z.array(browserSectionSchema),
+ excluded: z.array(browserExclusionSchema),
+ dropped_events: browserDroppedEventsSchema,
+});
+export type BrowserCompleteness = z.infer;
+
+/** Build canonical completeness output from one adapter-owned capture ledger. */
+export const classifyBrowserCompleteness = (input: {
+ readonly policyFilteredSections: ReadonlySet;
+ readonly attachLimitedSections: ReadonlySet;
+ readonly truncatedSections: ReadonlySet;
+ readonly unavailableSections: ReadonlySet;
+ readonly excluded: readonly BrowserExclusion[];
+ readonly droppedEvents: Omit;
+}): BrowserCompleteness => {
+ const policyFiltered = input.policyFilteredSections.size > 0;
+ const truncated =
+ input.truncatedSections.size > 0 ||
+ Object.values(input.droppedEvents).some((count) => count > 0);
+ const attachLimited =
+ input.attachLimitedSections.size > 0 || input.unavailableSections.size > 0;
+ const status = truncated
+ ? "truncated"
+ : policyFiltered
+ ? "policy_filtered"
+ : attachLimited
+ ? "attach_limited"
+ : "complete_within_window";
+ const conditions = [
+ ...(attachLimited ? (["attach_limited"] as const) : []),
+ ...(policyFiltered ? (["policy_filtered"] as const) : []),
+ ...(truncated ? (["truncated"] as const) : []),
+ ];
+ const droppedTotal = Object.values(input.droppedEvents).reduce(
+ (sum, count) => sum + count,
+ 0,
+ );
+ return browserCompletenessSchema.parse({
+ status,
+ conditions:
+ conditions.length === 0 ? ["complete_within_window"] : conditions,
+ policy_filtered_sections: sortedSections(input.policyFilteredSections),
+ attach_limited_sections: sortedSections(input.attachLimitedSections),
+ truncated_sections: sortedSections(input.truncatedSections),
+ unavailable_sections: sortedSections(input.unavailableSections),
+ excluded: canonicalExclusions(input.excluded),
+ dropped_events: { ...input.droppedEvents, total: droppedTotal },
+ });
+};
+
+const sortedSections = (
+ sections: ReadonlySet,
+): BrowserSection[] => [...sections].sort();
+
+const canonicalExclusions = (
+ exclusions: readonly BrowserExclusion[],
+): BrowserExclusion[] =>
+ [...exclusions].sort(
+ (left, right) =>
+ left.section.localeCompare(right.section) ||
+ left.reason.localeCompare(right.reason),
+ );
diff --git a/src/domain/browserObservation.ts b/src/domain/browserObservation.ts
index a04f57dcd..c94f43f92 100644
--- a/src/domain/browserObservation.ts
+++ b/src/domain/browserObservation.ts
@@ -1,5 +1,9 @@
import { z } from "zod";
+import { browserCompletenessSchema } from "./browserCompleteness.js";
+import { webTextArtifactSchema } from "./webContentArtifact.js";
+import { jsonShapeSchema } from "./jsonShape.js";
+
const parseExactOrigin = (value: string): string | undefined => {
let url: URL;
try {
@@ -78,7 +82,7 @@ export const browserEndpointSchema = z
return url.origin;
});
-const allowedOriginsSchema = z
+export const browserAllowedOriginsSchema = z
.array(browserOriginSchema)
.min(1)
.max(32)
@@ -86,7 +90,7 @@ const allowedOriginsSchema = z
const approvedBrowserInput = {
cdp_endpoint: browserEndpointSchema,
- allowed_origins: allowedOriginsSchema,
+ allowed_origins: browserAllowedOriginsSchema,
approved: z
.literal(true)
.describe("Explicit approval for browser observation"),
@@ -103,6 +107,18 @@ const browserInspectionLimitsSchema = z.object({
max_frames: z.number().int().min(1).max(1_000).default(200),
max_dom_nodes: z.number().int().min(1).max(10_000).default(2_000),
max_ax_nodes: z.number().int().min(1).max(10_000).default(2_000),
+ max_ax_text_field_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(16 * 1_024)
+ .default(1_024),
+ max_total_ax_text_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(1_024 * 1_024)
+ .default(64 * 1_024),
max_scripts: z.number().int().min(1).max(1_000).default(200),
max_resources: z.number().int().min(1).max(10_000).default(2_000),
max_workers: z.number().int().min(1).max(5_000).default(500),
@@ -121,13 +137,53 @@ const browserInspectionLimitsSchema = z.object({
.default(4 * 1_024 * 1_024),
max_network_events: z.number().int().min(1).max(10_000).default(1_000),
max_console_events: z.number().int().min(1).max(2_000).default(200),
+ max_console_text_field_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(16 * 1_024)
+ .default(1_024),
+ max_total_console_text_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(1_024 * 1_024)
+ .default(64 * 1_024),
+ max_json_body_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(4 * 1_024 * 1_024)
+ .default(1_024 * 1_024),
+ max_total_json_body_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(16 * 1_024 * 1_024)
+ .default(4 * 1_024 * 1_024),
+ max_json_shape_nodes: z.number().int().min(1).max(100_000).default(5_000),
+ max_json_shape_depth: z.number().int().min(1).max(100).default(20),
max_websocket_events: z.number().int().min(1).max(5_000).default(500),
+ max_websocket_shape_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(1_024 * 1_024)
+ .default(64 * 1_024),
+ max_total_websocket_shape_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(16 * 1_024 * 1_024)
+ .default(1_024 * 1_024),
});
const DEFAULT_BROWSER_INSPECTION_LIMITS = {
max_frames: 200,
max_dom_nodes: 2_000,
max_ax_nodes: 2_000,
+ max_ax_text_field_bytes: 1_024,
+ max_total_ax_text_bytes: 64 * 1_024,
max_scripts: 200,
max_resources: 2_000,
max_workers: 500,
@@ -136,7 +192,15 @@ const DEFAULT_BROWSER_INSPECTION_LIMITS = {
max_total_script_source_bytes: 4 * 1_024 * 1_024,
max_network_events: 1_000,
max_console_events: 200,
+ max_console_text_field_bytes: 1_024,
+ max_total_console_text_bytes: 64 * 1_024,
+ max_json_body_bytes: 1_024 * 1_024,
+ max_total_json_body_bytes: 4 * 1_024 * 1_024,
+ max_json_shape_nodes: 5_000,
+ max_json_shape_depth: 20,
max_websocket_events: 500,
+ max_websocket_shape_bytes: 64 * 1_024,
+ max_total_websocket_shape_bytes: 1_024 * 1_024,
} as const;
/** Public input for one passive, bounded inspection of an existing page. */
@@ -145,6 +209,13 @@ export const inspectWebPageInputSchema = z
...approvedBrowserInput,
target_id: z.string().trim().min(1).max(256),
observation_ms: z.number().int().min(0).max(10_000).default(500),
+ include_accessibility_text: z.boolean().default(false),
+ include_console_text: z.boolean().default(false),
+ console_text_approved: z.boolean().default(false),
+ include_json_body_shapes: z.boolean().default(false),
+ json_body_schema_approved: z.boolean().default(false),
+ include_websocket_shapes: z.boolean().default(false),
+ websocket_shape_approved: z.boolean().default(false),
include_script_sources: z.boolean().default(false),
include_storage_keys: z.boolean().default(false),
limits: browserInspectionLimitsSchema.default(
@@ -161,6 +232,66 @@ export const inspectWebPageInputSchema = z
path: ["limits", "max_script_source_bytes"],
message: "Per-script source limit cannot exceed the total source limit",
});
+ for (const [include, approved, path, message] of [
+ [
+ input.include_console_text,
+ input.console_text_approved,
+ "console_text_approved",
+ "Console text capture requires separate approval",
+ ],
+ [
+ input.include_json_body_shapes,
+ input.json_body_schema_approved,
+ "json_body_schema_approved",
+ "JSON body schema capture requires separate approval",
+ ],
+ [
+ input.include_websocket_shapes,
+ input.websocket_shape_approved,
+ "websocket_shape_approved",
+ "WebSocket shape capture requires separate approval",
+ ],
+ ] as const)
+ if (include && !approved)
+ context.addIssue({ code: "custom", path: [path], message });
+ if (
+ input.limits.max_console_text_field_bytes >
+ input.limits.max_total_console_text_bytes
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["limits", "max_console_text_field_bytes"],
+ message:
+ "Per-field console text limit cannot exceed the total text limit",
+ });
+ if (
+ input.limits.max_json_body_bytes > input.limits.max_total_json_body_bytes
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["limits", "max_json_body_bytes"],
+ message: "Per-body JSON limit cannot exceed the total body limit",
+ });
+ if (
+ input.limits.max_websocket_shape_bytes >
+ input.limits.max_total_websocket_shape_bytes
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["limits", "max_websocket_shape_bytes"],
+ message:
+ "Per-frame WebSocket limit cannot exceed the total frame limit",
+ });
+ if (
+ input.limits.max_ax_text_field_bytes >
+ input.limits.max_total_ax_text_bytes
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["limits", "max_ax_text_field_bytes"],
+ message:
+ "Per-field accessibility text limit cannot exceed the total text limit",
+ });
});
export type ListBrowserTargetsInput = z.infer<
@@ -280,13 +411,22 @@ const browserScriptSourceSchema = z.discriminatedUnion("included", [
z.object({ included: z.literal(false), reason: z.string() }),
z.object({
included: z.literal(true),
- sha256: z.string().regex(/^[a-f0-9]{64}$/u),
- bytes: z.number().int().min(0),
- content: z.string(),
+ artifact: webTextArtifactSchema,
+ }),
+]);
+const browserResourceReconciliationSchema = z.discriminatedUnion("status", [
+ z.object({ status: z.literal("exact"), resource_key: z.string() }),
+ z.object({
+ status: z.literal("ambiguous"),
+ candidate_resource_keys: z.array(z.string()),
+ }),
+ z.object({
+ status: z.literal("unmatched"),
+ reason: z.literal("no_exact_sanitized_url"),
}),
]);
const browserScriptSchema = z.object({
- script_id: z.string(),
+ script_key: z.string().regex(/^scr_[a-f0-9]{64}(?:_[0-9]+)?$/u),
url: z.string(),
origin: z.string().nullable(),
cdp_hash: z.string(),
@@ -294,9 +434,11 @@ const browserScriptSchema = z.object({
is_module: z.boolean(),
language: z.string().nullable(),
source_map_url: z.string().nullable(),
+ resource_reconciliation: browserResourceReconciliationSchema,
source: browserScriptSourceSchema,
});
const browserResourceSchema = z.object({
+ resource_key: z.string().regex(/^res_[a-f0-9]{64}$/u),
url: z.string(),
origin: z.string().nullable(),
type: z.string(),
@@ -318,6 +460,17 @@ const browserNetworkRequestSchema = z.object({
line: z.number().int().min(0).nullable(),
column: z.number().int().min(0).nullable(),
}),
+ body_shapes: z.object({
+ status: z.enum([
+ "not_approved",
+ "included",
+ "partial",
+ "unavailable",
+ "truncated",
+ ]),
+ request: jsonShapeSchema.nullable(),
+ response: jsonShapeSchema.nullable(),
+ }),
});
const browserConsoleEventSchema = z.object({
type: z.string(),
@@ -326,12 +479,31 @@ const browserConsoleEventSchema = z.object({
url: z.string().nullable(),
line: z.number().int().min(0).nullable(),
column: z.number().int().min(0).nullable(),
+ text_capture: z.object({
+ status: z.enum(["not_approved", "included", "truncated"]),
+ values: z.array(
+ z.object({
+ argument_index: z.number().int().min(0),
+ type: z.string(),
+ text: z.string(),
+ }),
+ ),
+ retained_bytes: z.number().int().min(0),
+ truncated_values: z.number().int().min(0),
+ }),
});
const browserWebSocketEventSchema = z.object({
request_id: z.string(),
direction: z.enum(["sent", "received"]),
opcode: z.number().int().min(0),
payload_bytes: z.number().int().min(0),
+ payload_shape: z
+ .object({
+ format: z.enum(["json", "text", "binary"]),
+ json_shape: jsonShapeSchema.nullable(),
+ truncated: z.boolean(),
+ })
+ .nullable(),
});
const browserWorkerSchema = z.object({
target_id: z.string(),
@@ -340,10 +512,80 @@ const browserWorkerSchema = z.object({
origin: z.string().nullable(),
attached: z.boolean(),
});
+const browserCspSourceSchema = z.object({
+ kind: z.enum([
+ "keyword",
+ "scheme",
+ "approved_origin",
+ "external_origin",
+ "other",
+ ]),
+ value: z.string().nullable(),
+});
+const browserLinkMetadataSchema = z.object({
+ href: z.string().nullable(),
+ destination_scope: z.enum(["approved", "outside_policy", "unsupported"]),
+ rel: z.array(z.string()),
+ as: z.string().nullable(),
+ type: z.string().nullable(),
+ crossorigin: z.string().nullable(),
+});
+const browserAgentHintSchema = z.object({
+ mechanism: z.enum([
+ "link_rel",
+ "dom_link_rel",
+ "well_known_resource",
+ "response_header",
+ ]),
+ declaration: z.string(),
+ url: z.string().nullable(),
+ trust: z.literal("page-declared-untrusted"),
+});
+const browserSafeMetadataSchema = z.object({
+ responses: z.array(
+ z.object({
+ request_id: z.string(),
+ url: z.string(),
+ mime_type: z.string().nullable(),
+ content_length: z.number().int().min(0).nullable(),
+ content_encoding: z.string().nullable(),
+ csp: z.object({
+ directives: z.array(
+ z.object({
+ name: z.string(),
+ sources: z.array(browserCspSourceSchema),
+ }),
+ ),
+ nonce_count: z.number().int().min(0),
+ hash_count: z.number().int().min(0),
+ }),
+ links: z.array(browserLinkMetadataSchema),
+ policies: z.object({
+ coop: z.string().nullable(),
+ coep: z.string().nullable(),
+ corp: z.string().nullable(),
+ referrer_policy: z.string().nullable(),
+ x_content_type_options: z.string().nullable(),
+ permissions_policy_features: z.array(z.string()),
+ }),
+ }),
+ ),
+ dom_urls: z.array(
+ z.object({
+ node_index: z.number().int().min(0),
+ attribute: z.enum(["href", "src", "action", "formaction", "poster"]),
+ url: z.string().nullable(),
+ destination_scope: z.enum(["approved", "outside_policy", "unsupported"]),
+ }),
+ ),
+ agent_hints: z.array(browserAgentHintSchema),
+ excluded_dom_urls: z.number().int().min(0),
+ headers_allowlisted: z.literal(true),
+});
/** Provider-neutral normalized result for one passive web-page observation. */
export const webPageInspectionSchema = z.object({
- schema_version: z.literal(1),
+ schema_version: z.literal(2),
browser: browserVersionSchema,
target: browserTargetSchema,
capture_window: z.object({
@@ -351,11 +593,7 @@ export const webPageInspectionSchema = z.object({
ended_at: z.iso.datetime(),
observation_ms: z.number().int().min(0),
}),
- completeness: z.object({
- status: z.enum(["complete", "truncated"]),
- truncated_sections: z.array(z.string()),
- dropped_events: z.number().int().min(0),
- }),
+ completeness: browserCompletenessSchema,
frames: z.array(browserFrameSchema),
dom: z.object({
total_nodes: z.number().int().min(0),
@@ -363,6 +601,12 @@ export const webPageInspectionSchema = z.object({
}),
accessibility: z.object({
total_nodes: z.number().int().min(0),
+ text_capture: z.object({
+ status: z.enum(["not_approved", "included", "truncated", "unavailable"]),
+ retained_bytes: z.number().int().min(0),
+ excluded_fields: z.number().int().min(0),
+ truncated_fields: z.number().int().min(0),
+ }),
nodes: z.array(browserAxNodeSchema),
}),
scripts: z.object({
@@ -382,6 +626,7 @@ export const webPageInspectionSchema = z.object({
prior_activity_available: z.literal(false),
}),
workers: z.array(browserWorkerSchema),
+ metadata: browserSafeMetadataSchema,
storage: z.object({
origin: z.string(),
usage_bytes: z.number().min(0).nullable(),
diff --git a/src/domain/browserSession.ts b/src/domain/browserSession.ts
new file mode 100644
index 000000000..313b7a5a8
--- /dev/null
+++ b/src/domain/browserSession.ts
@@ -0,0 +1,74 @@
+import { z } from "zod";
+
+import {
+ browserAllowedOriginsSchema,
+ browserEndpointSchema,
+} from "./browserObservation.js";
+import { browserCompletenessSchema } from "./browserCompleteness.js";
+
+/** Input for a bounded, navigation-aware browser observation window. */
+export const observeWebSessionInputSchema = z.object({
+ cdp_endpoint: browserEndpointSchema,
+ allowed_origins: browserAllowedOriginsSchema,
+ target_id: z.string().trim().min(1).max(256),
+ approved: z.literal(true),
+ observation_ms: z.number().int().min(1).max(60_000).default(10_000),
+ max_timeline_events: z.number().int().min(1).max(20_000).default(2_000),
+});
+export type ObserveWebSessionInput = z.infer<
+ typeof observeWebSessionInputSchema
+>;
+
+const timelineEventSchema = z.object({
+ sequence: z.number().int().min(1),
+ type: z.enum([
+ "navigation_requested",
+ "navigation_committed",
+ "same_origin_reload",
+ "same_document_navigation",
+ "redirect",
+ "load_failed",
+ "lifecycle",
+ "target_terminated",
+ ]),
+ timestamp: z.number().min(0),
+ frame_id: z.string().nullable(),
+ loader_id: z.string().nullable(),
+ request_id: z.string().nullable(),
+ url: z.string().nullable(),
+ destination_scope: z
+ .enum(["approved", "outside_policy", "unsupported"])
+ .nullable(),
+ detail: z.string().nullable(),
+});
+
+/** Navigation-aware session result for external user actions. */
+export const webObservationSessionSchema = z.object({
+ schema_version: z.literal(1),
+ browser: z.object({
+ product: z.string(),
+ protocol_version: z.string(),
+ revision: z.string(),
+ user_agent: z.string(),
+ js_version: z.string(),
+ }),
+ target: z.object({
+ target_id: z.string(),
+ initial_url: z.string(),
+ final_url: z.string().nullable(),
+ }),
+ window: z.object({
+ armed_at: z.iso.datetime(),
+ ended_at: z.iso.datetime(),
+ requested_ms: z.number().int().min(1),
+ end_reason: z.enum([
+ "window_elapsed",
+ "target_left_scope",
+ "target_terminated",
+ ]),
+ }),
+ timeline: z.array(timelineEventSchema),
+ completeness: browserCompletenessSchema,
+ limitations: z.array(z.string()),
+});
+export type WebObservationSession = z.infer;
diff --git a/src/domain/electronObservation.ts b/src/domain/electronObservation.ts
new file mode 100644
index 000000000..3c6b911f3
--- /dev/null
+++ b/src/domain/electronObservation.ts
@@ -0,0 +1,194 @@
+import { isAbsolute } from "node:path";
+
+import { z } from "zod";
+
+import { browserCompletenessSchema } from "./browserCompleteness.js";
+import { browserEndpointSchema } from "./browserObservation.js";
+import { webTextArtifactSchema } from "./webContentArtifact.js";
+
+/** Absolute operator-approved filesystem roots for Electron file pages. */
+export const electronFileRootsSchema = z
+ .array(
+ z
+ .string()
+ .min(1)
+ .max(16_384)
+ .refine(isAbsolute, "Electron file roots must be absolute paths"),
+ )
+ .min(1)
+ .max(32)
+ .transform((roots) => [...new Set(roots)].sort());
+
+const approvedElectronInput = {
+ cdp_endpoint: browserEndpointSchema,
+ allowed_file_roots: electronFileRootsSchema,
+ approved: z.literal(true),
+};
+
+/** Input for listing root-confined file:// page targets from Electron CDP. */
+export const listElectronTargetsInputSchema = z.object({
+ ...approvedElectronInput,
+ offset: z.number().int().min(0).default(0),
+ limit: z.number().int().min(1).max(200).default(100),
+});
+export type ListElectronTargetsInput = z.infer<
+ typeof listElectronTargetsInputSchema
+>;
+
+/** Input for passive structural inspection of one Electron file page. */
+export const inspectElectronPageInputSchema = z
+ .object({
+ ...approvedElectronInput,
+ target_id: z.string().trim().min(1).max(256),
+ observation_ms: z.number().int().min(0).max(10_000).default(100),
+ include_script_sources: z.boolean().default(false),
+ source_capture_approved: z.boolean().default(false),
+ limits: z
+ .object({
+ max_frames: z.number().int().min(1).max(1_000).default(200),
+ max_dom_nodes: z.number().int().min(1).max(10_000).default(2_000),
+ max_scripts: z.number().int().min(1).max(2_000).default(500),
+ max_resources: z.number().int().min(1).max(10_000).default(2_000),
+ max_script_source_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(4 * 1_024 * 1_024)
+ .default(1_024 * 1_024),
+ max_total_script_source_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(16 * 1_024 * 1_024)
+ .default(4 * 1_024 * 1_024),
+ })
+ .default({
+ max_frames: 200,
+ max_dom_nodes: 2_000,
+ max_scripts: 500,
+ max_resources: 2_000,
+ max_script_source_bytes: 1_024 * 1_024,
+ max_total_script_source_bytes: 4 * 1_024 * 1_024,
+ }),
+ })
+ .superRefine((input, context) => {
+ if (input.include_script_sources && !input.source_capture_approved)
+ context.addIssue({
+ code: "custom",
+ path: ["source_capture_approved"],
+ message: "Electron script source capture requires separate approval",
+ });
+ if (
+ input.limits.max_script_source_bytes >
+ input.limits.max_total_script_source_bytes
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["limits", "max_script_source_bytes"],
+ message: "Per-script source limit cannot exceed the total source limit",
+ });
+ });
+export type InspectElectronPageInput = z.infer<
+ typeof inspectElectronPageInputSchema
+>;
+
+const browserVersionSchema = z.object({
+ product: z.string(),
+ protocol_version: z.string(),
+ revision: z.string(),
+ user_agent: z.string(),
+ js_version: z.string(),
+});
+const electronTargetSchema = z.object({
+ target_id: z.string(),
+ type: z.string(),
+ title: z.string(),
+ file_path: z.string(),
+ attached: z.boolean(),
+});
+
+/** Root-filtered Electron file target inventory. */
+export const electronTargetListSchema = z.object({
+ schema_version: z.literal(1),
+ browser: browserVersionSchema,
+ targets: z.object({
+ items: z.array(electronTargetSchema),
+ offset: z.number().int().min(0),
+ limit: z.number().int().min(1),
+ total: z.number().int().min(0),
+ next_offset: z.number().int().min(0).nullable(),
+ has_more: z.boolean(),
+ }),
+ excluded: z.object({
+ outside_root: z.number().int().min(0),
+ unsupported_url: z.number().int().min(0),
+ non_page: z.number().int().min(0),
+ }),
+ limitations: z.array(z.string()),
+});
+export type ElectronTargetList = z.infer;
+
+const electronSourceSchema = z.discriminatedUnion("included", [
+ z.object({ included: z.literal(false), reason: z.string() }),
+ z.object({ included: z.literal(true), artifact: webTextArtifactSchema }),
+]);
+
+/** Provider-neutral passive Electron file-page structure and script inventory. */
+export const electronPageInspectionSchema = z.object({
+ schema_version: z.literal(1),
+ browser: browserVersionSchema,
+ target: electronTargetSchema,
+ capture_window: z.object({
+ started_at: z.iso.datetime(),
+ ended_at: z.iso.datetime(),
+ observation_ms: z.number().int().min(0),
+ }),
+ completeness: browserCompletenessSchema,
+ frames: z.array(
+ z.object({
+ frame_id: z.string(),
+ parent_frame_id: z.string().nullable(),
+ file_path: z.string(),
+ }),
+ ),
+ dom: z.object({
+ total_nodes: z.number().int().min(0),
+ nodes: z.array(
+ z.object({
+ index: z.number().int().min(0),
+ parent_index: z.number().int().min(-1),
+ node_type: z.number().int().min(0),
+ node_name: z.string(),
+ node_value_length: z.number().int().min(0),
+ attribute_names: z.array(z.string()),
+ }),
+ ),
+ }),
+ scripts: z.object({
+ total: z.number().int().min(0),
+ items: z.array(
+ z.object({
+ script_key: z.string().regex(/^electron_script_[a-f0-9]{64}$/u),
+ file_path: z.string(),
+ cdp_hash: z.string(),
+ length: z.number().int().min(0),
+ is_module: z.boolean(),
+ language: z.string().nullable(),
+ source: electronSourceSchema,
+ }),
+ ),
+ }),
+ resources: z.array(
+ z.object({
+ resource_key: z.string().regex(/^electron_resource_[a-f0-9]{64}$/u),
+ file_path: z.string(),
+ type: z.string(),
+ mime_type: z.string(),
+ content_size: z.number().min(0).nullable(),
+ }),
+ ),
+ limitations: z.array(z.string()),
+});
+export type ElectronPageInspection = z.infer<
+ typeof electronPageInspectionSchema
+>;
diff --git a/src/domain/errors.ts b/src/domain/errors.ts
index 5f3414cbb..60469562d 100644
--- a/src/domain/errors.ts
+++ b/src/domain/errors.ts
@@ -144,12 +144,25 @@ export class ProviderAdapterError extends AnalysisError {
}
}
+/** Public browser and Electron operations that can fail at a CDP boundary. */
+export type BrowserObservationOperation =
+ | "list_browser_targets"
+ | "inspect_web_page"
+ | "analyze_web_bundle"
+ | "observe_web_session"
+ | "discover_webmcp_tools"
+ | "compare_web_captures"
+ | "capture_web_screenshot"
+ | "compare_web_screenshots"
+ | "list_electron_targets"
+ | "inspect_electron_page";
+
/** A bounded passive browser observation failed at its CDP boundary. */
export class BrowserObservationError extends AnalysisError {
readonly _tag = "BrowserObservationError";
constructor(
- readonly operation: "list_browser_targets" | "inspect_web_page",
+ readonly operation: BrowserObservationOperation,
readonly reason:
| "endpoint_unreachable"
| "invalid_endpoint_response"
diff --git a/src/domain/jsonShape.ts b/src/domain/jsonShape.ts
new file mode 100644
index 000000000..1d7271386
--- /dev/null
+++ b/src/domain/jsonShape.ts
@@ -0,0 +1,151 @@
+import { z } from "zod";
+
+const jsonValueTypeSchema = z.enum([
+ "object",
+ "array",
+ "string",
+ "number",
+ "boolean",
+ "null",
+]);
+type JsonValueType = z.infer;
+
+/** Value-free structural summary of one approved JSON payload. */
+export const jsonShapeSchema = z.object({
+ root_type: jsonValueTypeSchema,
+ node_count: z.number().int().min(1),
+ max_depth_observed: z.number().int().min(0),
+ properties: z.array(
+ z.object({
+ path: z.string(),
+ types: z.array(jsonValueTypeSchema).min(1),
+ observations: z.number().int().min(1),
+ }),
+ ),
+ truncated: z.boolean(),
+});
+export type JsonShape = z.infer;
+
+export interface JsonShapeLimits {
+ readonly maximumBytes: number;
+ readonly maximumNodes: number;
+ readonly maximumDepth: number;
+}
+
+/** Parse approved JSON and immediately discard values after iterative shape inference. */
+export const inferJsonShape = (
+ text: string,
+ limits: JsonShapeLimits,
+): JsonShape | null => {
+ if (Buffer.byteLength(text) > limits.maximumBytes) return null;
+ let root: unknown;
+ try {
+ root = JSON.parse(text);
+ } catch {
+ return null;
+ }
+ const properties = new Map<
+ string,
+ { readonly types: Set; observations: number }
+ >();
+ const pending: Array<{
+ readonly value: unknown;
+ readonly path: string;
+ readonly depth: number;
+ }> = [{ value: root, path: "", depth: 0 }];
+ let nodeCount = 0;
+ let maxDepthObserved = 0;
+ let truncated = false;
+ while (pending.length > 0) {
+ const current = pending.pop();
+ if (current === undefined) break;
+ if (nodeCount >= limits.maximumNodes) {
+ truncated = true;
+ break;
+ }
+ nodeCount += 1;
+ maxDepthObserved = Math.max(maxDepthObserved, current.depth);
+ if (current.depth >= limits.maximumDepth) {
+ if (hasChildren(current.value)) truncated = true;
+ continue;
+ }
+ if (Array.isArray(current.value)) {
+ const capacity = Math.max(
+ 0,
+ limits.maximumNodes - nodeCount - pending.length,
+ );
+ const retained = Math.min(current.value.length, capacity);
+ if (retained < current.value.length) truncated = true;
+ for (let index = retained - 1; index >= 0; index -= 1)
+ pending.push({
+ value: current.value[index],
+ path: `${current.path}/*`,
+ depth: current.depth + 1,
+ });
+ continue;
+ }
+ if (!isRecord(current.value)) continue;
+ const allEntries = Object.entries(current.value);
+ const capacity = Math.max(
+ 0,
+ limits.maximumNodes - nodeCount - pending.length,
+ );
+ const entries = allEntries.slice(0, capacity);
+ if (entries.length < allEntries.length) truncated = true;
+ for (let index = entries.length - 1; index >= 0; index -= 1) {
+ const entry = entries[index];
+ if (entry === undefined) continue;
+ const [name, value] = entry;
+ const path = `${current.path}/${pointerName(name)}`.slice(0, 2_048);
+ const type = jsonValueType(value);
+ const existing = properties.get(path);
+ if (existing === undefined)
+ properties.set(path, { types: new Set([type]), observations: 1 });
+ else {
+ existing.types.add(type);
+ existing.observations += 1;
+ }
+ pending.push({ value, path, depth: current.depth + 1 });
+ }
+ }
+ return jsonShapeSchema.parse({
+ root_type: jsonValueType(root),
+ node_count: nodeCount,
+ max_depth_observed: maxDepthObserved,
+ properties: [...properties.entries()]
+ .map(([path, value]) => ({
+ path,
+ types: [...value.types].sort(),
+ observations: value.observations,
+ }))
+ .sort((left, right) => left.path.localeCompare(right.path))
+ .slice(0, limits.maximumNodes),
+ truncated,
+ });
+};
+
+const jsonValueType = (value: unknown): JsonValueType => {
+ if (value === null) return "null";
+ if (Array.isArray(value)) return "array";
+ switch (typeof value) {
+ case "string":
+ return "string";
+ case "number":
+ return "number";
+ case "boolean":
+ return "boolean";
+ default:
+ return "object";
+ }
+};
+
+const hasChildren = (value: unknown): boolean =>
+ Array.isArray(value)
+ ? value.length > 0
+ : isRecord(value) && Object.keys(value).length > 0;
+
+const isRecord = (value: unknown): value is Readonly> =>
+ typeof value === "object" && value !== null && !Array.isArray(value);
+
+const pointerName = (value: string): string =>
+ value.slice(0, 256).replaceAll("~", "~0").replaceAll("/", "~1");
diff --git a/src/domain/permissionPolicy.ts b/src/domain/permissionPolicy.ts
index 917dff5e9..f4e369725 100644
--- a/src/domain/permissionPolicy.ts
+++ b/src/domain/permissionPolicy.ts
@@ -6,6 +6,7 @@ import { err, ok, type Result } from "./result.js";
export type PermissionCapability =
| "process_capture"
| "browser_observe"
+ | "electron_observe"
| "evidence_read"
| "evidence_write"
| "investigation_input"
diff --git a/src/domain/webBundleAnalysis.ts b/src/domain/webBundleAnalysis.ts
new file mode 100644
index 000000000..3c88bbf85
--- /dev/null
+++ b/src/domain/webBundleAnalysis.ts
@@ -0,0 +1,228 @@
+import { z } from "zod";
+
+import { inspectWebPageInputSchema } from "./browserObservation.js";
+import { webTextArtifactSchema } from "./webContentArtifact.js";
+
+const webBundleLimitsSchema = z.object({
+ max_findings: z.number().int().min(1).max(10_000).default(1_000),
+ max_ast_nodes: z.number().int().min(1).max(2_000_000).default(250_000),
+ max_source_maps: z.number().int().min(1).max(1_000).default(100),
+ max_source_map_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(16 * 1_024 * 1_024)
+ .default(4 * 1_024 * 1_024),
+ max_total_source_map_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(64 * 1_024 * 1_024)
+ .default(16 * 1_024 * 1_024),
+ max_source_map_mappings: z.number().int().min(1).max(100_000).default(10_000),
+ max_original_sources: z.number().int().min(1).max(20_000).default(2_000),
+});
+
+/** Capture-and-analyze input with separate source and source-map approvals. */
+export const analyzeWebBundleInputSchema = inspectWebPageInputSchema
+ .safeExtend({
+ include_script_sources: z.literal(true).default(true),
+ source_capture_approved: z.literal(true),
+ fetch_source_maps: z.boolean().default(false),
+ source_map_fetch_approved: z.boolean().default(false),
+ analysis_limits: webBundleLimitsSchema.default({
+ max_findings: 1_000,
+ max_ast_nodes: 250_000,
+ max_source_maps: 100,
+ max_source_map_bytes: 4 * 1_024 * 1_024,
+ max_total_source_map_bytes: 16 * 1_024 * 1_024,
+ max_source_map_mappings: 10_000,
+ max_original_sources: 2_000,
+ }),
+ })
+ .superRefine((input, context) => {
+ if (input.fetch_source_maps && !input.source_map_fetch_approved)
+ context.addIssue({
+ code: "custom",
+ path: ["source_map_fetch_approved"],
+ message: "Source-map network fetch requires separate approval",
+ });
+ if (
+ input.analysis_limits.max_source_map_bytes >
+ input.analysis_limits.max_total_source_map_bytes
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["analysis_limits", "max_source_map_bytes"],
+ message:
+ "Per-map source-map byte limit cannot exceed the aggregate limit",
+ });
+ });
+export type AnalyzeWebBundleInput = z.infer;
+
+const sourceLocationSchema = z.object({
+ script_key: z.string(),
+ line: z.number().int().min(1).nullable(),
+ column: z.number().int().min(0).nullable(),
+});
+
+const basisSchema = z.object({
+ script_key: z.string(),
+ artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+ line: z.number().int().min(1).nullable(),
+ column: z.number().int().min(0).nullable(),
+ detector: z.string(),
+});
+
+const findingSchema = z.object({
+ value: z.string(),
+ mechanism: z.string(),
+ location: sourceLocationSchema,
+});
+
+const sourceMapSchema = z.object({
+ script_key: z.string(),
+ declared_url: z.string(),
+ status: z.enum([
+ "included",
+ "fetch_failed",
+ "invalid",
+ "policy_filtered",
+ "truncated",
+ ]),
+ artifact: webTextArtifactSchema.nullable(),
+ original_sources: z.array(
+ z.object({
+ source: z.string(),
+ artifact: webTextArtifactSchema.nullable(),
+ }),
+ ),
+ original_module_edges: z.array(
+ z.object({
+ from_source: z.string(),
+ kind: z.enum(["static_import", "dynamic_import", "require"]),
+ specifier: z.string(),
+ resolved_source: z.string().nullable(),
+ }),
+ ),
+ mappings: z.array(
+ z.object({
+ generated_line: z.number().int().min(1),
+ generated_column: z.number().int().min(0),
+ source: z.string(),
+ original_line: z.number().int().min(1),
+ original_column: z.number().int().min(0),
+ name: z.string().nullable(),
+ }),
+ ),
+ limitation: z.string().nullable(),
+});
+
+const webTextArtifactSummarySchema = z.object({
+ uri: z.string().regex(/^rea:\/\/web-content\/sha256\/[a-f0-9]{64}$/u),
+ sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+ bytes: z.number().int().min(0),
+ media_type: z.string().min(1).max(256),
+ charset: z.literal("utf-8"),
+ text_available: z.literal(true),
+});
+
+const sourceMapsSchema = z
+ .object({
+ status: z.enum([
+ "not_requested",
+ "included",
+ "partial",
+ "unavailable",
+ "truncated",
+ ]),
+ requested: z.number().int().min(0),
+ processed: z.number().int().min(0),
+ dropped: z.number().int().min(0),
+ dropped_script_keys: z.array(z.string()),
+ items: z.array(sourceMapSchema),
+ })
+ .superRefine((sourceMaps, context) => {
+ if (
+ sourceMaps.requested !== sourceMaps.processed + sourceMaps.dropped ||
+ sourceMaps.processed !== sourceMaps.items.length ||
+ sourceMaps.dropped !== sourceMaps.dropped_script_keys.length
+ )
+ context.addIssue({
+ code: "custom",
+ message: "Source-map coverage counts are inconsistent",
+ });
+ });
+
+/** Provider-neutral result of bounded JavaScript bundle reverse engineering. */
+export const webBundleAnalysisSchema = z.object({
+ schema_version: z.literal(1),
+ capture: z.object({
+ target_url: z.string(),
+ scripts_observed: z.number().int().min(0),
+ scripts_analyzed: z.number().int().min(0),
+ source_artifacts: z.array(webTextArtifactSummarySchema),
+ }),
+ observations: z.object({
+ chunks: z.object({
+ nodes: z.array(
+ z.object({
+ script_key: z.string(),
+ url: z.string(),
+ artifact_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+ bytes: z.number().int().min(0),
+ }),
+ ),
+ edges: z.array(
+ z.object({
+ from_script_key: z.string(),
+ kind: z.enum([
+ "static_import",
+ "dynamic_import",
+ "require",
+ "worker_import",
+ ]),
+ specifier: z.string(),
+ resolved_url: z.string().nullable(),
+ location: sourceLocationSchema,
+ }),
+ ),
+ }),
+ routes: z.array(findingSchema),
+ endpoints: z.array(findingSchema),
+ webmcp_declarations: z.array(
+ z.object({
+ name: z.string().nullable(),
+ description: z.string().nullable(),
+ schema_property_names: z.array(z.string()),
+ trust: z.literal("page-declared-untrusted"),
+ location: sourceLocationSchema,
+ }),
+ ),
+ source_maps: sourceMapsSchema,
+ }),
+ inferences: z.array(
+ z.object({
+ kind: z.enum(["vendor_fingerprint", "route_framework", "bundle_runtime"]),
+ value: z.string(),
+ confidence: z.enum(["low", "medium", "high"]),
+ basis: z.array(basisSchema).min(1),
+ }),
+ ),
+ unknowns: z.array(
+ z.object({
+ dimension: z.string(),
+ reason: z.string(),
+ affected_script_keys: z.array(z.string()),
+ }),
+ ),
+ completeness: z.object({
+ status: z.enum(["complete_within_limits", "truncated", "partial"]),
+ parsed_scripts: z.number().int().min(0),
+ parse_failures: z.number().int().min(0),
+ visited_ast_nodes: z.number().int().min(0),
+ dropped_findings: z.number().int().min(0),
+ }),
+ limitations: z.array(z.string()),
+});
+export type WebBundleAnalysis = z.infer;
diff --git a/src/domain/webBundleAnalyzer.ts b/src/domain/webBundleAnalyzer.ts
new file mode 100644
index 000000000..19881f492
--- /dev/null
+++ b/src/domain/webBundleAnalyzer.ts
@@ -0,0 +1,640 @@
+import { parse } from "@babel/parser";
+import * as t from "@babel/types";
+
+import type { WebPageInspection } from "./browserObservation.js";
+import { sanitizeBrowserUrl } from "./browserObservation.js";
+import {
+ webBundleAnalysisSchema,
+ type AnalyzeWebBundleInput,
+ type WebBundleAnalysis,
+} from "./webBundleAnalysis.js";
+
+type BundleObservations = WebBundleAnalysis["observations"];
+type ChunkEdge = BundleObservations["chunks"]["edges"][number];
+type Finding = BundleObservations["routes"][number];
+type WebMcpDeclaration = BundleObservations["webmcp_declarations"][number];
+type Inference = WebBundleAnalysis["inferences"][number];
+type BrowserScript = WebPageInspection["scripts"]["items"][number];
+type IncludedSource = Extract;
+type IncludedScript = Omit & {
+ readonly source: IncludedSource;
+};
+
+interface AnalysisAccumulator {
+ readonly edges: ChunkEdge[];
+ readonly routes: Finding[];
+ readonly endpoints: Finding[];
+ readonly webMcp: WebMcpDeclaration[];
+ readonly inferences: Inference[];
+ readonly seen: Set;
+ visitedNodes: number;
+ parsedScripts: number;
+ parseFailures: number;
+ droppedFindings: number;
+ astLimitReached: boolean;
+}
+
+/** Analyze captured, explicitly approved JavaScript source without execution. */
+export const analyzeCapturedWebBundle = (
+ inspection: WebPageInspection,
+ input: AnalyzeWebBundleInput,
+ sourceMaps: BundleObservations["source_maps"] = {
+ status: "not_requested",
+ requested: 0,
+ processed: 0,
+ dropped: 0,
+ dropped_script_keys: [],
+ items: [],
+ },
+): WebBundleAnalysis => {
+ const accumulator = emptyAccumulator();
+ const sourceScripts = inspection.scripts.items.filter(isIncludedScript);
+ for (const script of sourceScripts) analyzeScript(script, input, accumulator);
+ const unavailable = inspection.scripts.items
+ .filter((script) => !script.source.included)
+ .map(({ script_key }) => script_key);
+ const sourceMapIncomplete =
+ sourceMaps.status === "partial" || sourceMaps.status === "unavailable";
+ const partial =
+ accumulator.parseFailures > 0 ||
+ unavailable.length > 0 ||
+ sourceMapIncomplete;
+ const truncated =
+ accumulator.astLimitReached ||
+ accumulator.droppedFindings > 0 ||
+ sourceMaps.status === "truncated";
+ return webBundleAnalysisSchema.parse({
+ schema_version: 1,
+ capture: {
+ target_url: inspection.target.url,
+ scripts_observed: inspection.scripts.total,
+ scripts_analyzed: sourceScripts.length,
+ source_artifacts: sourceScripts.map((script) => {
+ if (!script.source.included)
+ throw new TypeError("Filtered source changed");
+ const { text: _text, ...artifact } = script.source.artifact;
+ return { ...artifact, text_available: true };
+ }),
+ },
+ observations: {
+ chunks: {
+ nodes: sourceScripts.map((script) => {
+ if (!script.source.included)
+ throw new TypeError("Filtered source changed");
+ return {
+ script_key: script.script_key,
+ url: script.url,
+ artifact_sha256: script.source.artifact.sha256,
+ bytes: script.source.artifact.bytes,
+ };
+ }),
+ edges: accumulator.edges,
+ },
+ routes: accumulator.routes,
+ endpoints: accumulator.endpoints,
+ webmcp_declarations: accumulator.webMcp,
+ source_maps: sourceMaps,
+ },
+ inferences: accumulator.inferences,
+ unknowns: [
+ ...(unavailable.length === 0
+ ? []
+ : [
+ {
+ dimension: "script_source",
+ reason: "Source artifact was not captured within approved limits",
+ affected_script_keys: unavailable,
+ },
+ ]),
+ ...(accumulator.parseFailures === 0
+ ? []
+ : [
+ {
+ dimension: "javascript_ast",
+ reason: "One or more source artifacts could not be parsed",
+ affected_script_keys: sourceScripts.map(
+ ({ script_key }) => script_key,
+ ),
+ },
+ ]),
+ ...(sourceMaps.status === "not_requested" ||
+ sourceMaps.status === "included"
+ ? []
+ : [
+ {
+ dimension: "source_maps",
+ reason:
+ sourceMaps.status === "truncated"
+ ? "Source-map evidence was truncated by approved limits"
+ : "One or more requested source maps were unavailable or incomplete",
+ affected_script_keys: [
+ ...new Set([
+ ...sourceMaps.items
+ .filter(({ status }) => status !== "included")
+ .map(({ script_key }) => script_key),
+ ...sourceMaps.dropped_script_keys,
+ ]),
+ ].sort(),
+ },
+ ]),
+ ],
+ completeness: {
+ status: truncated
+ ? "truncated"
+ : partial
+ ? "partial"
+ : "complete_within_limits",
+ parsed_scripts: accumulator.parsedScripts,
+ parse_failures: accumulator.parseFailures,
+ visited_ast_nodes: accumulator.visitedNodes,
+ dropped_findings: accumulator.droppedFindings,
+ },
+ limitations: [
+ "Static bundle findings are observations or bounded inferences; REA does not execute captured JavaScript.",
+ "String-built routes and endpoints, encrypted configuration, and server-side behavior may remain unknown.",
+ "Page-declared WebMCP metadata is untrusted and is never registered or invoked as an REA tool.",
+ ],
+ });
+};
+
+const analyzeScript = (
+ script: IncludedScript,
+ input: AnalyzeWebBundleInput,
+ accumulator: AnalysisAccumulator,
+): void => {
+ let file: ReturnType;
+ try {
+ file = parse(script.source.artifact.text, {
+ sourceType: "unambiguous",
+ errorRecovery: true,
+ plugins: ["jsx", "typescript"],
+ });
+ } catch {
+ accumulator.parseFailures += 1;
+ return;
+ }
+ accumulator.parsedScripts += 1;
+ detectVendorFingerprints(
+ script,
+ accumulator,
+ input.analysis_limits.max_findings,
+ );
+ t.traverseFast(file, (node) => {
+ accumulator.visitedNodes += 1;
+ if (accumulator.visitedNodes > input.analysis_limits.max_ast_nodes) {
+ accumulator.astLimitReached = true;
+ return t.traverseFast.stop;
+ }
+ inspectNode(script, node, accumulator, input.analysis_limits.max_findings);
+ return undefined;
+ });
+};
+
+const inspectNode = (
+ script: IncludedScript,
+ node: t.Node,
+ accumulator: AnalysisAccumulator,
+ maximumFindings: number,
+): void => {
+ if (
+ (t.isImportDeclaration(node) || t.isExportAllDeclaration(node)) &&
+ node.source !== undefined
+ )
+ addEdge(
+ script,
+ node.source.value,
+ "static_import",
+ node,
+ accumulator,
+ maximumFindings,
+ );
+ else if (t.isExportNamedDeclaration(node) && node.source != null)
+ addEdge(
+ script,
+ node.source.value,
+ "static_import",
+ node,
+ accumulator,
+ maximumFindings,
+ );
+ else if (t.isImportExpression(node) && t.isStringLiteral(node.source))
+ addEdge(
+ script,
+ node.source.value,
+ "dynamic_import",
+ node,
+ accumulator,
+ maximumFindings,
+ );
+ if (t.isObjectProperty(node))
+ inspectRouteProperty(script, node, accumulator, maximumFindings);
+ if (t.isCallExpression(node) || t.isNewExpression(node))
+ inspectCall(script, node, accumulator, maximumFindings);
+};
+
+const inspectCall = (
+ script: IncludedScript,
+ node: t.CallExpression | t.NewExpression,
+ accumulator: AnalysisAccumulator,
+ maximumFindings: number,
+): void => {
+ const name = calleeName(node.callee);
+ const first = stringArgument(node.arguments[0]);
+ if ((name === "require" || name.endsWith(".require")) && first !== undefined)
+ addEdge(script, first, "require", node, accumulator, maximumFindings);
+ if (
+ (name === "importScripts" || name.endsWith(".importScripts")) &&
+ first !== undefined
+ )
+ addEdge(script, first, "worker_import", node, accumulator, maximumFindings);
+ if (
+ routeCallNames.some(
+ (candidate) => name === candidate || name.endsWith(`.${candidate}`),
+ )
+ ) {
+ if (first !== undefined)
+ addFinding(
+ accumulator.routes,
+ script,
+ first,
+ `call:${name}`,
+ node,
+ accumulator,
+ maximumFindings,
+ );
+ addRouteFrameworkInference(
+ script,
+ name,
+ node,
+ accumulator,
+ maximumFindings,
+ );
+ }
+ const endpoint = endpointArgument(name, node.arguments);
+ if (endpoint !== undefined)
+ addFinding(
+ accumulator.endpoints,
+ script,
+ endpoint,
+ `call:${name}`,
+ node,
+ accumulator,
+ maximumFindings,
+ );
+ if (
+ name.endsWith("modelContext.registerTool") ||
+ name === "modelContext.registerTool"
+ )
+ addWebMcpDeclaration(script, node, accumulator, maximumFindings);
+};
+
+const inspectRouteProperty = (
+ script: IncludedScript,
+ node: t.ObjectProperty,
+ accumulator: AnalysisAccumulator,
+ maximumFindings: number,
+): void => {
+ const key = propertyName(node.key);
+ if ((key === "path" || key === "route") && t.isStringLiteral(node.value))
+ addFinding(
+ accumulator.routes,
+ script,
+ node.value.value,
+ `property:${key}`,
+ node,
+ accumulator,
+ maximumFindings,
+ );
+};
+
+const addEdge = (
+ script: IncludedScript,
+ specifier: string,
+ kind: ChunkEdge["kind"],
+ node: t.Node,
+ accumulator: AnalysisAccumulator,
+ maximumFindings: number,
+): void => {
+ const bounded = specifier.slice(0, 4_096);
+ const key = `edge\0${script.script_key}\0${kind}\0${bounded}`;
+ addBounded(accumulator, key, maximumFindings, () =>
+ accumulator.edges.push({
+ from_script_key: script.script_key,
+ kind,
+ specifier: bounded,
+ resolved_url: resolveSpecifier(bounded, script.url),
+ location: location(script.script_key, node),
+ }),
+ );
+};
+
+const addFinding = (
+ collection: Finding[],
+ script: IncludedScript,
+ rawValue: string,
+ mechanism: string,
+ node: t.Node,
+ accumulator: AnalysisAccumulator,
+ maximumFindings: number,
+): void => {
+ const value = sanitizeCandidate(rawValue);
+ const key = `finding\0${mechanism}\0${script.script_key}\0${value}`;
+ addBounded(accumulator, key, maximumFindings, () =>
+ collection.push({
+ value,
+ mechanism,
+ location: location(script.script_key, node),
+ }),
+ );
+};
+
+const addWebMcpDeclaration = (
+ script: IncludedScript,
+ node: t.CallExpression | t.NewExpression,
+ accumulator: AnalysisAccumulator,
+ maximumFindings: number,
+): void => {
+ const declaration = node.arguments[0];
+ if (!t.isObjectExpression(declaration)) return;
+ const name = objectString(declaration, "name");
+ const description = objectString(declaration, "description");
+ const schema =
+ objectValue(declaration, "inputSchema") ??
+ objectValue(declaration, "input_schema");
+ const declaredProperties = t.isObjectExpression(schema)
+ ? objectValue(schema, "properties")
+ : undefined;
+ const propertyObject = t.isObjectExpression(declaredProperties)
+ ? declaredProperties
+ : schema;
+ const schemaPropertyNames = t.isObjectExpression(propertyObject)
+ ? propertyObject.properties.flatMap((property) =>
+ t.isObjectProperty(property)
+ ? [propertyName(property.key)].filter(Boolean)
+ : [],
+ )
+ : [];
+ const key = `webmcp\0${script.script_key}\0${name ?? ""}\0${schemaPropertyNames.join("\0")}`;
+ addBounded(accumulator, key, maximumFindings, () =>
+ accumulator.webMcp.push({
+ name: name?.slice(0, 256) ?? null,
+ description: description?.slice(0, 2_048) ?? null,
+ schema_property_names: [...new Set(schemaPropertyNames)]
+ .sort()
+ .slice(0, 256),
+ trust: "page-declared-untrusted",
+ location: location(script.script_key, node),
+ }),
+ );
+};
+
+const detectVendorFingerprints = (
+ script: IncludedScript,
+ accumulator: AnalysisAccumulator,
+ maximumFindings: number,
+): void => {
+ const text = script.source.artifact.text;
+ for (const detector of vendorDetectors) {
+ if (!detector.patterns.some((pattern) => text.includes(pattern))) continue;
+ const key = `vendor\0${script.script_key}\0${detector.value}`;
+ addBounded(accumulator, key, maximumFindings, () =>
+ accumulator.inferences.push({
+ kind: detector.kind,
+ value: detector.value,
+ confidence: detector.confidence,
+ basis: [basis(script, detector.detector)],
+ }),
+ );
+ }
+};
+
+const addRouteFrameworkInference = (
+ script: IncludedScript,
+ name: string,
+ node: t.Node,
+ accumulator: AnalysisAccumulator,
+ maximumFindings: number,
+): void => {
+ const value =
+ name.endsWith("useRoutes") || name.endsWith("createBrowserRouter")
+ ? "React Router-compatible route API"
+ : "Generic route registration API";
+ const key = `route-framework\0${script.script_key}\0${value}`;
+ addBounded(accumulator, key, maximumFindings, () =>
+ accumulator.inferences.push({
+ kind: "route_framework",
+ value,
+ confidence: "medium",
+ basis: [{ ...basis(script, `call:${name}`), ...locationFields(node) }],
+ }),
+ );
+};
+
+const addBounded = (
+ accumulator: AnalysisAccumulator,
+ key: string,
+ maximum: number,
+ add: () => void,
+): void => {
+ if (accumulator.seen.has(key)) return;
+ const findings =
+ accumulator.edges.length +
+ accumulator.routes.length +
+ accumulator.endpoints.length +
+ accumulator.webMcp.length +
+ accumulator.inferences.length;
+ if (findings >= maximum) {
+ accumulator.droppedFindings += 1;
+ return;
+ }
+ accumulator.seen.add(key);
+ add();
+};
+
+const endpointArgument = (
+ name: string,
+ args: readonly (
+ | t.Expression
+ | t.SpreadElement
+ | t.JSXNamespacedName
+ | t.ArgumentPlaceholder
+ )[],
+): string | undefined => {
+ if (name === "fetch" || name.endsWith(".fetch") || name === "WebSocket")
+ return stringArgument(args[0]);
+ if (name.endsWith(".open") && stringArgument(args[1]) !== undefined)
+ return stringArgument(args[1]);
+ if (
+ ["get", "post", "put", "patch", "delete", "request"].some(
+ (method) => name === method || name.endsWith(`.${method}`),
+ )
+ )
+ return stringArgument(args[0]);
+ return undefined;
+};
+
+const calleeName = (callee: t.Node): string => {
+ if (t.isIdentifier(callee)) return callee.name;
+ if (t.isImport(callee)) return "import";
+ if (t.isMemberExpression(callee) || t.isOptionalMemberExpression(callee)) {
+ const object = t.isExpression(callee.object)
+ ? calleeName(callee.object)
+ : "";
+ const property = propertyName(callee.property);
+ return object === "" ? property : `${object}.${property}`;
+ }
+ return "";
+};
+
+const stringArgument = (
+ value: t.Node | null | undefined,
+): string | undefined => (t.isStringLiteral(value) ? value.value : undefined);
+
+const propertyName = (value: t.Node): string => {
+ if (t.isIdentifier(value)) return value.name;
+ if (t.isStringLiteral(value)) return value.value;
+ return "";
+};
+
+const objectValue = (
+ object: t.ObjectExpression,
+ name: string,
+): t.ObjectProperty["value"] | undefined => {
+ for (const property of object.properties)
+ if (t.isObjectProperty(property) && propertyName(property.key) === name)
+ return property.value;
+ return undefined;
+};
+
+const objectString = (
+ object: t.ObjectExpression,
+ name: string,
+): string | undefined => {
+ const value = objectValue(object, name);
+ return t.isStringLiteral(value) ? value.value : undefined;
+};
+
+const resolveSpecifier = (specifier: string, base: string): string | null => {
+ try {
+ const resolved = new URL(specifier, base);
+ if (resolved.protocol !== "http:" && resolved.protocol !== "https:")
+ return null;
+ return sanitizeBrowserUrl(resolved.href).url;
+ } catch {
+ return null;
+ }
+};
+
+const sanitizeCandidate = (value: string): string => {
+ const bounded = value.slice(0, 4_096);
+ try {
+ const parsed = new URL(bounded, "https://rea.invalid");
+ const sanitized = sanitizeBrowserUrl(parsed.href).url;
+ return parsed.origin === "https://rea.invalid"
+ ? sanitized.replace("https://rea.invalid", "")
+ : sanitized;
+ } catch {
+ return bounded.split("#", 1)[0]?.split("?", 1)[0] ?? "";
+ }
+};
+
+const location = (scriptKey: string, node: t.Node) => ({
+ script_key: scriptKey,
+ ...locationFields(node),
+});
+
+const locationFields = (node: t.Node) => ({
+ line: node.loc?.start.line ?? null,
+ column: node.loc?.start.column ?? null,
+});
+
+const basis = (script: IncludedScript, detector: string) => ({
+ script_key: script.script_key,
+ artifact_sha256: script.source.artifact.sha256,
+ line: null,
+ column: null,
+ detector,
+});
+
+const emptyAccumulator = (): AnalysisAccumulator => ({
+ edges: [],
+ routes: [],
+ endpoints: [],
+ webMcp: [],
+ inferences: [],
+ seen: new Set(),
+ visitedNodes: 0,
+ parsedScripts: 0,
+ parseFailures: 0,
+ droppedFindings: 0,
+ astLimitReached: false,
+});
+
+const isIncludedScript = (script: BrowserScript): script is IncludedScript =>
+ script.source.included;
+
+const routeCallNames = [
+ "route",
+ "addRoute",
+ "useRoutes",
+ "createBrowserRouter",
+ "createHashRouter",
+] as const;
+
+const vendorDetectors: readonly {
+ readonly value: string;
+ readonly detector: string;
+ readonly patterns: readonly string[];
+ readonly confidence: Inference["confidence"];
+ readonly kind: Inference["kind"];
+}[] = [
+ {
+ value: "webpack",
+ detector: "webpack-runtime",
+ patterns: ["__webpack_require__"],
+ confidence: "high",
+ kind: "bundle_runtime",
+ },
+ {
+ value: "Vite",
+ detector: "vite-runtime",
+ patterns: ["__vite__", "import.meta.hot"],
+ confidence: "medium",
+ kind: "bundle_runtime",
+ },
+ {
+ value: "React",
+ detector: "react-runtime",
+ patterns: ["__REACT_DEVTOOLS_GLOBAL_HOOK__", "React.createElement"],
+ confidence: "medium",
+ kind: "vendor_fingerprint",
+ },
+ {
+ value: "Vue",
+ detector: "vue-runtime",
+ patterns: ["__VUE__", "createApp("],
+ confidence: "medium",
+ kind: "vendor_fingerprint",
+ },
+ {
+ value: "Next.js",
+ detector: "next-runtime",
+ patterns: ["__NEXT_DATA__", "/_next/"],
+ confidence: "high",
+ kind: "vendor_fingerprint",
+ },
+ {
+ value: "Angular",
+ detector: "angular-runtime",
+ patterns: ["ɵɵdefineComponent"],
+ confidence: "high",
+ kind: "vendor_fingerprint",
+ },
+ {
+ value: "Svelte",
+ detector: "svelte-runtime",
+ patterns: ["svelte/internal"],
+ confidence: "medium",
+ kind: "vendor_fingerprint",
+ },
+];
diff --git a/src/domain/webCaptureDiff.ts b/src/domain/webCaptureDiff.ts
new file mode 100644
index 000000000..a89b2bb0d
--- /dev/null
+++ b/src/domain/webCaptureDiff.ts
@@ -0,0 +1,286 @@
+import { createHash } from "node:crypto";
+
+import canonicalize from "canonicalize";
+import { z } from "zod";
+
+import {
+ webPageInspectionSchema,
+ type WebPageInspection,
+} from "./browserObservation.js";
+import {
+ webMcpDiscoverySchema,
+ type WebMcpDiscovery,
+} from "./webMcpDiscovery.js";
+
+const captureSnapshotSchema = z.object({
+ inspection: webPageInspectionSchema,
+ webmcp: webMcpDiscoverySchema.nullable().default(null),
+});
+
+/** Input for deterministic comparison of two normalized web captures. */
+export const compareWebCapturesInputSchema = z.object({
+ before: captureSnapshotSchema,
+ after: captureSnapshotSchema,
+ max_changes: z.number().int().min(1).max(20_000).default(2_000),
+});
+export type CompareWebCapturesInput = z.infer<
+ typeof compareWebCapturesInputSchema
+>;
+
+const changeSchema = z.object({
+ identity: z.string(),
+ change: z.enum(["added", "removed", "modified"]),
+});
+const dimensionSchema = z.object({
+ status: z.enum(["changed", "unchanged", "unknown"]),
+ total_changes: z.number().int().min(0),
+ changes: z.array(changeSchema),
+ omitted_changes: z.number().int().min(0),
+ reason: z.string().nullable(),
+});
+
+/** Completeness-aware changes across stable browser evidence dimensions. */
+export const webCaptureDiffSchema = z.object({
+ schema_version: z.literal(1),
+ overall_status: z.enum(["changed", "unchanged", "unknown"]),
+ before_target: z.object({ target_id: z.string(), url: z.string() }),
+ after_target: z.object({ target_id: z.string(), url: z.string() }),
+ dimensions: z.object({
+ dom_structure: dimensionSchema,
+ scripts: dimensionSchema,
+ resources: dimensionSchema,
+ network: dimensionSchema,
+ metadata: dimensionSchema,
+ webmcp: dimensionSchema,
+ }),
+ limitations: z.array(z.string()),
+});
+export type WebCaptureDiff = z.infer;
+type Dimension =
+ WebCaptureDiff["dimensions"][keyof WebCaptureDiff["dimensions"]];
+type Change = Dimension["changes"][number];
+
+/** Compare normalized observations without treating incomplete absence as proof. */
+export const compareWebCaptures = (
+ input: CompareWebCapturesInput,
+): WebCaptureDiff => {
+ let remaining = input.max_changes;
+ const dimension = (
+ before: ReadonlyMap,
+ after: ReadonlyMap,
+ complete: boolean,
+ reason: string,
+ ): Dimension => {
+ const all = compareIdentities(before, after);
+ const retained = all.slice(0, remaining);
+ remaining -= retained.length;
+ return {
+ status: all.length > 0 ? "changed" : complete ? "unchanged" : "unknown",
+ total_changes: all.length,
+ changes: retained,
+ omitted_changes: all.length - retained.length,
+ reason: all.length === 0 && !complete ? reason : null,
+ };
+ };
+ const before = input.before.inspection;
+ const after = input.after.inspection;
+ const dimensions = {
+ dom_structure: dimension(
+ singleton("document", digest(domProjection(before))),
+ singleton("document", digest(domProjection(after))),
+ sectionsComplete(before, ["frames", "dom"]) &&
+ sectionsComplete(after, ["frames", "dom"]),
+ "DOM or frame capture was incomplete in at least one observation.",
+ ),
+ scripts: dimension(
+ keyed(
+ before.scripts.items.map(scriptProjection),
+ (item) => item.script_key,
+ ),
+ keyed(
+ after.scripts.items.map(scriptProjection),
+ (item) => item.script_key,
+ ),
+ sectionsComplete(before, ["scripts"]) &&
+ sectionsComplete(after, ["scripts"]),
+ "Script inventory was incomplete in at least one observation.",
+ ),
+ resources: dimension(
+ keyed(before.resources, (item) => item.resource_key),
+ keyed(after.resources, (item) => item.resource_key),
+ sectionsComplete(before, ["resources"]) &&
+ sectionsComplete(after, ["resources"]),
+ "Resource inventory was incomplete in at least one observation.",
+ ),
+ network: dimension(
+ networkMap(before),
+ networkMap(after),
+ sectionsComplete(before, ["network_requests"]) &&
+ sectionsComplete(after, ["network_requests"]),
+ "Network capture is attach-window limited or incomplete.",
+ ),
+ metadata: dimension(
+ singleton("metadata", digest(metadataProjection(before))),
+ singleton("metadata", digest(metadataProjection(after))),
+ sectionsComplete(before, ["metadata"]) &&
+ sectionsComplete(after, ["metadata"]),
+ "Safe metadata capture was incomplete in at least one observation.",
+ ),
+ webmcp: dimension(
+ webMcpMap(input.before.webmcp),
+ webMcpMap(input.after.webmcp),
+ webMcpComplete(input.before.webmcp) && webMcpComplete(input.after.webmcp),
+ "WebMCP discovery was unavailable or incomplete in at least one capture.",
+ ),
+ };
+ const statuses = Object.values(dimensions).map(({ status }) => status);
+ return webCaptureDiffSchema.parse({
+ schema_version: 1,
+ overall_status: statuses.includes("changed")
+ ? "changed"
+ : statuses.includes("unknown")
+ ? "unknown"
+ : "unchanged",
+ before_target: {
+ target_id: before.target.target_id,
+ url: before.target.url,
+ },
+ after_target: {
+ target_id: after.target.target_id,
+ url: after.target.url,
+ },
+ dimensions,
+ limitations: [
+ "A changed status proves an observed difference; an unknown status means absence could not be established from capture completeness.",
+ "Network comparison covers only activity observed after each CDP attachment.",
+ ],
+ });
+};
+
+const compareIdentities = (
+ before: ReadonlyMap,
+ after: ReadonlyMap,
+): Change[] => {
+ const changes: Change[] = [];
+ for (const [identity, fingerprint] of before) {
+ const next = after.get(identity);
+ if (next === undefined) changes.push({ identity, change: "removed" });
+ else if (next !== fingerprint)
+ changes.push({ identity, change: "modified" });
+ }
+ for (const identity of after.keys())
+ if (!before.has(identity)) changes.push({ identity, change: "added" });
+ return changes.sort(
+ (left, right) =>
+ left.identity.localeCompare(right.identity) ||
+ left.change.localeCompare(right.change),
+ );
+};
+
+const keyed = (
+ values: readonly T[],
+ identity: (value: T) => string,
+): ReadonlyMap =>
+ new Map(values.map((value) => [identity(value), digest(value)]));
+
+const networkMap = (
+ inspection: WebPageInspection,
+): ReadonlyMap => {
+ const grouped = new Map();
+ for (const request of inspection.network.requests) {
+ const identity = `net_${digest({
+ method: request.method,
+ url: request.url,
+ resource_type: request.resource_type,
+ })}`;
+ const values = grouped.get(identity) ?? [];
+ values.push({
+ status: request.status,
+ mime_type: request.mime_type,
+ encoded_data_length: request.encoded_data_length,
+ initiator: request.initiator,
+ body_shapes: request.body_shapes,
+ });
+ grouped.set(identity, values);
+ }
+ return new Map(
+ [...grouped].map(([identity, values]) => [
+ identity,
+ digest(values.map((value) => digest(value)).sort()),
+ ]),
+ );
+};
+
+const webMcpMap = (
+ discovery: WebMcpDiscovery | null,
+): ReadonlyMap =>
+ discovery === null
+ ? new Map()
+ : keyed(discovery.tools.items, (tool) => tool.tool_key);
+
+const webMcpComplete = (discovery: WebMcpDiscovery | null): boolean =>
+ discovery !== null &&
+ discovery.status === "available" &&
+ !incompleteSections(discovery.completeness).has("webmcp_tools");
+
+const sectionsComplete = (
+ inspection: WebPageInspection,
+ sections: readonly string[],
+): boolean => {
+ const incomplete = incompleteSections(inspection.completeness);
+ return sections.every((section) => !incomplete.has(section));
+};
+
+const incompleteSections = (completeness: {
+ readonly policy_filtered_sections: readonly string[];
+ readonly attach_limited_sections: readonly string[];
+ readonly truncated_sections: readonly string[];
+ readonly unavailable_sections: readonly string[];
+}): ReadonlySet =>
+ new Set([
+ ...completeness.policy_filtered_sections,
+ ...completeness.attach_limited_sections,
+ ...completeness.truncated_sections,
+ ...completeness.unavailable_sections,
+ ]);
+
+const domProjection = (inspection: WebPageInspection) => ({
+ frames: inspection.frames
+ .map(({ url, origin }) => ({ url, origin }))
+ .sort((left, right) => left.url.localeCompare(right.url)),
+ nodes: inspection.dom.nodes.map(({ index: _index, ...node }) => node),
+});
+
+const scriptProjection = (
+ script: WebPageInspection["scripts"]["items"][number],
+) => ({
+ script_key: script.script_key,
+ url: script.url,
+ cdp_hash: script.cdp_hash,
+ length: script.length,
+ is_module: script.is_module,
+ language: script.language,
+ source_map_url: script.source_map_url,
+});
+
+const metadataProjection = (inspection: WebPageInspection) => ({
+ responses: inspection.metadata.responses
+ .map(({ request_id: _requestId, ...response }) => response)
+ .map((value) => digest(value))
+ .sort(),
+ dom_urls: inspection.metadata.dom_urls.map((value) => digest(value)).sort(),
+ agent_hints: inspection.metadata.agent_hints
+ .map((value) => digest(value))
+ .sort(),
+ excluded_dom_urls: inspection.metadata.excluded_dom_urls,
+ headers_allowlisted: inspection.metadata.headers_allowlisted,
+});
+
+const singleton = (key: string, value: string): ReadonlyMap =>
+ new Map([[key, value]]);
+
+const digest = (value: unknown): string => {
+ const encoded = canonicalize(value);
+ if (encoded === undefined) throw new TypeError("Expected canonical JSON");
+ return createHash("sha256").update(encoded).digest("hex");
+};
diff --git a/src/domain/webContentArtifact.ts b/src/domain/webContentArtifact.ts
new file mode 100644
index 000000000..308d4d874
--- /dev/null
+++ b/src/domain/webContentArtifact.ts
@@ -0,0 +1,56 @@
+import { createHash } from "node:crypto";
+
+import { z } from "zod";
+
+/** Self-verifying text artifact used by web-source analysis boundaries. */
+export const webTextArtifactSchema = z
+ .object({
+ uri: z.string().regex(/^rea:\/\/web-content\/sha256\/[a-f0-9]{64}$/u),
+ sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+ bytes: z.number().int().min(0),
+ media_type: z.string().min(1).max(256),
+ charset: z.literal("utf-8"),
+ text: z.string(),
+ })
+ .superRefine((artifact, context) => {
+ const bytes = Buffer.byteLength(artifact.text);
+ const digest = createHash("sha256").update(artifact.text).digest("hex");
+ if (artifact.bytes !== bytes)
+ context.addIssue({
+ code: "custom",
+ path: ["bytes"],
+ message: "Byte count mismatch",
+ });
+ if (artifact.sha256 !== digest)
+ context.addIssue({
+ code: "custom",
+ path: ["sha256"],
+ message: "Digest mismatch",
+ });
+ if (artifact.uri !== webContentUri(digest))
+ context.addIssue({
+ code: "custom",
+ path: ["uri"],
+ message: "Content URI mismatch",
+ });
+ });
+export type WebTextArtifact = z.infer;
+
+/** Build an immutable content-addressed UTF-8 text artifact. */
+export const createWebTextArtifact = (
+ text: string,
+ mediaType: string,
+): WebTextArtifact => {
+ const sha256 = createHash("sha256").update(text).digest("hex");
+ return {
+ uri: webContentUri(sha256),
+ sha256,
+ bytes: Buffer.byteLength(text),
+ media_type: mediaType,
+ charset: "utf-8",
+ text,
+ };
+};
+
+const webContentUri = (sha256: string): string =>
+ `rea://web-content/sha256/${sha256}`;
diff --git a/src/domain/webInventory.ts b/src/domain/webInventory.ts
new file mode 100644
index 000000000..d3f8a2edb
--- /dev/null
+++ b/src/domain/webInventory.ts
@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+
+import canonicalize from "canonicalize";
+
+export interface WebInventoryResourceInput {
+ readonly url: string;
+ readonly origin: string | null;
+ readonly type: string;
+ readonly mime_type: string;
+ readonly content_size: number | null;
+}
+
+export interface WebInventoryScriptInput {
+ readonly url: string;
+ readonly cdp_hash: string;
+ readonly length: number;
+ readonly is_module: boolean;
+ readonly language: string | null;
+ readonly source_map_url: string | null;
+}
+
+export interface StableWebResource extends WebInventoryResourceInput {
+ readonly resource_key: string;
+}
+
+export type WebResourceReconciliation =
+ | { readonly status: "exact"; readonly resource_key: string }
+ | { readonly status: "ambiguous"; readonly candidate_resource_keys: string[] }
+ | { readonly status: "unmatched"; readonly reason: "no_exact_sanitized_url" };
+
+/** Assign deterministic identities to a bounded resource inventory. */
+export const stableWebResources = (
+ resources: readonly WebInventoryResourceInput[],
+): StableWebResource[] => {
+ const keyed = resources.map((resource) => ({
+ ...resource,
+ resource_key: `res_${digest(resource)}`,
+ }));
+ return [
+ ...new Map(
+ keyed.map((resource) => [resource.resource_key, resource]),
+ ).values(),
+ ].sort(
+ (left, right) =>
+ left.resource_key.localeCompare(right.resource_key) ||
+ left.url.localeCompare(right.url),
+ );
+};
+
+/** Reconcile one script with resource-tree observations without fuzzy matching. */
+export const reconcileWebScript = (
+ script: WebInventoryScriptInput,
+ resources: readonly StableWebResource[],
+): WebResourceReconciliation => {
+ const candidates = resources.filter(
+ (resource) => resource.url === script.url,
+ );
+ if (candidates.length === 1)
+ return { status: "exact", resource_key: candidates[0]?.resource_key ?? "" };
+ if (candidates.length > 1)
+ return {
+ status: "ambiguous",
+ candidate_resource_keys: uniqueResourceKeys(candidates),
+ };
+ return { status: "unmatched", reason: "no_exact_sanitized_url" };
+};
+
+/** Prefer exact transient raw-URL matching, then report sanitized ambiguity. */
+export const reconcileCapturedWebScript = (
+ script: WebInventoryScriptInput & { readonly rawUrl: string },
+ rawResources: readonly (WebInventoryResourceInput & {
+ readonly rawUrl: string;
+ })[],
+ resources: readonly StableWebResource[],
+): WebResourceReconciliation => {
+ const exact = rawResources.filter(
+ (resource) => resource.rawUrl === script.rawUrl,
+ );
+ if (exact.length === 1) {
+ const resource = exact[0];
+ if (resource !== undefined) {
+ const { rawUrl: _rawUrl, ...publicResource } = resource;
+ const stable = stableWebResources([publicResource])[0];
+ if (stable !== undefined)
+ return { status: "exact", resource_key: stable.resource_key };
+ }
+ }
+ const candidates = resources.filter(
+ (resource) => resource.url === script.url,
+ );
+ if (candidates.length > 0)
+ return {
+ status: "ambiguous",
+ candidate_resource_keys: uniqueResourceKeys(candidates),
+ };
+ return { status: "unmatched", reason: "no_exact_sanitized_url" };
+};
+
+/** Stable script identity excludes target IDs, CDP script IDs, and timestamps. */
+export const stableWebScriptKey = (script: WebInventoryScriptInput): string =>
+ `scr_${digest({
+ url: script.url,
+ cdp_hash: script.cdp_hash,
+ length: script.length,
+ is_module: script.is_module,
+ language: script.language,
+ source_map_url: script.source_map_url,
+ })}`;
+
+const uniqueResourceKeys = (
+ resources: readonly StableWebResource[],
+): string[] =>
+ [...new Set(resources.map(({ resource_key }) => resource_key))].sort();
+
+const digest = (value: unknown): string => {
+ const encoded = canonicalize(value);
+ if (encoded === undefined)
+ throw new TypeError("Web inventory value is not canonical JSON");
+ return createHash("sha256").update(encoded).digest("hex");
+};
diff --git a/src/domain/webMcpDiscovery.ts b/src/domain/webMcpDiscovery.ts
new file mode 100644
index 000000000..ad3a4bde0
--- /dev/null
+++ b/src/domain/webMcpDiscovery.ts
@@ -0,0 +1,80 @@
+import { z } from "zod";
+
+import { browserCompletenessSchema } from "./browserCompleteness.js";
+import {
+ browserAllowedOriginsSchema,
+ browserEndpointSchema,
+} from "./browserObservation.js";
+import { jsonShapeSchema } from "./jsonShape.js";
+
+/** Input for passive discovery of page-registered WebMCP tools. */
+export const discoverWebMcpToolsInputSchema = z.object({
+ cdp_endpoint: browserEndpointSchema,
+ allowed_origins: browserAllowedOriginsSchema,
+ target_id: z.string().trim().min(1).max(256),
+ approved: z.literal(true),
+ observation_ms: z.number().int().min(0).max(10_000).default(100),
+ max_tools: z.number().int().min(1).max(5_000).default(500),
+ max_schema_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(1_024 * 1_024)
+ .default(256 * 1_024),
+ max_schema_nodes: z.number().int().min(1).max(100_000).default(5_000),
+ max_schema_depth: z.number().int().min(1).max(100).default(20),
+});
+export type DiscoverWebMcpToolsInput = z.infer<
+ typeof discoverWebMcpToolsInputSchema
+>;
+
+const browserVersionSchema = z.object({
+ product: z.string(),
+ protocol_version: z.string(),
+ revision: z.string(),
+ user_agent: z.string(),
+ js_version: z.string(),
+});
+
+const webMcpToolSchema = z.object({
+ tool_key: z.string().regex(/^webmcp_[a-f0-9]{64}$/u),
+ name: z.string(),
+ description: z.string(),
+ frame_id: z.string(),
+ frame_url: z.string(),
+ owner_origin: z.string(),
+ declaration_kind: z.enum(["declarative", "imperative"]),
+ input_schema_shape: jsonShapeSchema.nullable(),
+ annotations: z.object({
+ read_only: z.boolean().nullable(),
+ untrusted_content: z.boolean().nullable(),
+ autosubmit: z.boolean().nullable(),
+ }),
+ registration_source: z
+ .object({
+ url: z.string(),
+ line: z.number().int().min(0).nullable(),
+ column: z.number().int().min(0).nullable(),
+ })
+ .nullable(),
+ trust: z.literal("page-declared-untrusted"),
+});
+
+/** Passive WebMCP inventory; it intentionally has no invocation surface. */
+export const webMcpDiscoverySchema = z.object({
+ schema_version: z.literal(1),
+ browser: browserVersionSchema,
+ target: z.object({
+ target_id: z.string(),
+ url: z.string(),
+ origin: z.string(),
+ }),
+ status: z.enum(["available", "unavailable"]),
+ tools: z.object({
+ total: z.number().int().min(0),
+ items: z.array(webMcpToolSchema),
+ }),
+ completeness: browserCompletenessSchema,
+ limitations: z.array(z.string()),
+});
+export type WebMcpDiscovery = z.infer;
diff --git a/src/domain/webScreenshot.ts b/src/domain/webScreenshot.ts
new file mode 100644
index 000000000..7ae7a5645
--- /dev/null
+++ b/src/domain/webScreenshot.ts
@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+
+import { z } from "zod";
+
+import { browserCompletenessSchema } from "./browserCompleteness.js";
+import {
+ browserAllowedOriginsSchema,
+ browserEndpointSchema,
+} from "./browserObservation.js";
+
+const MAX_SCREENSHOT_BYTES = 8 * 1_024 * 1_024;
+
+/** Self-verifying inline PNG artifact for CLI/MCP parity. */
+const webScreenshotArtifactSchema = z
+ .object({
+ uri: z.string().regex(/^rea:\/\/web-screenshot\/sha256\/[a-f0-9]{64}$/u),
+ sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+ bytes: z.number().int().min(1).max(MAX_SCREENSHOT_BYTES),
+ media_type: z.literal("image/png"),
+ data_base64: z.string().max(Math.ceil((MAX_SCREENSHOT_BYTES * 4) / 3) + 4),
+ })
+ .superRefine((artifact, context) => {
+ const bytes = decodeCanonicalBase64(artifact.data_base64);
+ if (bytes === undefined) {
+ context.addIssue({ code: "custom", message: "Invalid canonical base64" });
+ return;
+ }
+ const sha256 = createHash("sha256").update(bytes).digest("hex");
+ if (
+ bytes.byteLength !== artifact.bytes ||
+ sha256 !== artifact.sha256 ||
+ artifact.uri !== `rea://web-screenshot/sha256/${sha256}`
+ )
+ context.addIssue({
+ code: "custom",
+ message: "Screenshot artifact digest or size mismatch",
+ });
+ });
+export type WebScreenshotArtifact = z.infer;
+
+/** Input for one read-only visible-viewport screenshot. */
+export const captureWebScreenshotInputSchema = z.object({
+ cdp_endpoint: browserEndpointSchema,
+ allowed_origins: browserAllowedOriginsSchema,
+ target_id: z.string().trim().min(1).max(256),
+ approved: z.literal(true),
+ screenshot_approved: z.literal(true),
+ maximum_image_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(MAX_SCREENSHOT_BYTES)
+ .default(4 * 1_024 * 1_024),
+});
+export type CaptureWebScreenshotInput = z.infer<
+ typeof captureWebScreenshotInputSchema
+>;
+
+const browserVersionSchema = z.object({
+ product: z.string(),
+ protocol_version: z.string(),
+ revision: z.string(),
+ user_agent: z.string(),
+ js_version: z.string(),
+});
+
+/** Bounded screenshot observation with embedded immutable artifact bytes. */
+export const webScreenshotSchema = z.object({
+ schema_version: z.literal(1),
+ browser: browserVersionSchema,
+ target: z.object({
+ target_id: z.string(),
+ url: z.string(),
+ origin: z.string(),
+ }),
+ captured_at: z.iso.datetime(),
+ viewport: z.object({
+ width: z.number().int().min(1),
+ height: z.number().int().min(1),
+ }),
+ artifact: webScreenshotArtifactSchema,
+ completeness: browserCompletenessSchema,
+ limitations: z.array(z.string()),
+});
+export type WebScreenshot = z.infer;
+
+/** Input for bounded local pixel comparison of two screenshot artifacts. */
+export const compareWebScreenshotsInputSchema = z.object({
+ before: webScreenshotArtifactSchema,
+ after: webScreenshotArtifactSchema,
+ channel_threshold: z.number().int().min(0).max(255).default(0),
+ maximum_pixels: z.number().int().min(1).max(32_000_000).default(16_000_000),
+});
+export type CompareWebScreenshotsInput = z.infer<
+ typeof compareWebScreenshotsInputSchema
+>;
+
+/** Value-only visual difference metrics; no OCR or image mutation. */
+export const webScreenshotDiffSchema = z.object({
+ schema_version: z.literal(1),
+ status: z.enum(["identical", "different", "dimension_mismatch"]),
+ before: z.object({
+ width: z.number().int().min(1),
+ height: z.number().int().min(1),
+ }),
+ after: z.object({
+ width: z.number().int().min(1),
+ height: z.number().int().min(1),
+ }),
+ channel_threshold: z.number().int().min(0).max(255),
+ compared_pixels: z.number().int().min(0),
+ changed_pixels: z.number().int().min(0).nullable(),
+ changed_ratio: z.number().min(0).max(1).nullable(),
+ maximum_channel_delta: z.number().int().min(0).max(255).nullable(),
+ mean_absolute_channel_delta: z.number().min(0).max(255).nullable(),
+ limitations: z.array(z.string()),
+});
+export type WebScreenshotDiff = z.infer;
+
+/** Create a content-addressed PNG artifact from already bounded bytes. */
+export const createWebScreenshotArtifact = (
+ bytes: Buffer,
+): WebScreenshotArtifact => {
+ const sha256 = createHash("sha256").update(bytes).digest("hex");
+ return webScreenshotArtifactSchema.parse({
+ uri: `rea://web-screenshot/sha256/${sha256}`,
+ sha256,
+ bytes: bytes.byteLength,
+ media_type: "image/png",
+ data_base64: bytes.toString("base64"),
+ });
+};
+
+/** Strict canonical base64 decoder used before digest validation. */
+export const decodeCanonicalBase64 = (value: string): Buffer | undefined => {
+ if (value.length === 0 || value.length % 4 !== 0 || !BASE64.test(value))
+ return undefined;
+ const decoded = Buffer.from(value, "base64");
+ return decoded.toString("base64") === value ? decoded : undefined;
+};
+
+const BASE64 = /^(?:[A-Za-z\d+/]{4})*(?:[A-Za-z\d+/]{2}==|[A-Za-z\d+/]{3}=)?$/u;
diff --git a/src/generatedPackageMetadata.ts b/src/generatedPackageMetadata.ts
index 3c11aee90..94b9d2129 100644
--- a/src/generatedPackageMetadata.ts
+++ b/src/generatedPackageMetadata.ts
@@ -1,9 +1,9 @@
/** Generated from package.json and package-lock.json; do not edit. */
export const PACKAGE_METADATA = {
name: "rea-agents",
- version: "1.4.0",
+ version: "1.5.0",
serverSdkVersion: "2.0.0-beta.4",
clientSdkVersion: "2.0.0-beta.4",
coreSdkVersion: "2.0.0-beta.4",
- skillVersion: "13",
+ skillVersion: "14",
} as const;
diff --git a/src/main.ts b/src/main.ts
index 05d06b301..7fc4a2c7e 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -16,6 +16,7 @@ import { projectAnalysisError } from "./domain/errors.js";
import { readProjectPermissionStore } from "./application/ProjectPermissionStore.js";
import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
import { CdpBrowserProvider } from "./browser/CdpBrowserProvider.js";
+import { CdpElectronProvider } from "./browser/CdpElectronProvider.js";
const MCP_CONNECTION_LOST =
"REA lost its MCP client connection. Restart REA from your MCP client.";
@@ -82,6 +83,7 @@ export const run = async (
const session = createBinarySession(config.value, logger);
const browserObservation = new CdpBrowserProvider();
+ const electronObservation = new CdpElectronProvider();
if (config.value.hopperTargetPath !== undefined) {
const opened = await session.open(config.value.hopperTargetPath, {
targetKind: config.value.hopperTargetKind,
@@ -129,6 +131,7 @@ export const run = async (
analysisSnapshotFilePolicy: runtimeSnapshotPolicy,
permissionAuthority: permissionAuthority.value,
browserObservation,
+ electronObservation,
artifactIntegrityContinueEnabled: () =>
currentConfig.artifactIntegrityContinueEnabled,
availabilityPolicy: () => ({
@@ -138,6 +141,10 @@ export const run = async (
currentConfig.browserObservationEnabled &&
currentConfig.browserCdpEndpoints.length > 0 &&
currentConfig.browserAllowedOrigins.length > 0,
+ electronObservationEnabled:
+ currentConfig.electronObservationEnabled &&
+ currentConfig.electronCdpEndpoints.length > 0 &&
+ currentConfig.electronFileRoots.length > 0,
}),
});
liveServers.add(server);
diff --git a/src/server/createServer.ts b/src/server/createServer.ts
index e14dfc392..97aface5e 100644
--- a/src/server/createServer.ts
+++ b/src/server/createServer.ts
@@ -17,6 +17,8 @@ import { createServerIdentity } from "../serverIdentity.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import type { BrowserObservationPort } from "../application/BrowserObservationPort.js";
import { registerBrowserTools } from "./registerBrowserTools.js";
+import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
+import { registerElectronTools } from "./registerElectronTools.js";
export interface CreateServerOptions {
readonly logger?: Logger;
@@ -26,11 +28,13 @@ export interface CreateServerOptions {
readonly analysisSnapshotFilePolicy?: EvidenceFilePolicy;
readonly permissionAuthority?: PermissionAuthority;
readonly browserObservation?: BrowserObservationPort;
+ readonly electronObservation?: ElectronObservationPort;
readonly artifactIntegrityContinueEnabled?: () => boolean;
readonly availabilityPolicy?: () => {
readonly processCaptureEnabled: boolean;
readonly evidenceFileRoots: number;
readonly browserObservationEnabled?: boolean;
+ readonly electronObservationEnabled?: boolean;
};
}
@@ -146,6 +150,12 @@ export const createServer = (
permissionAuthority: options.permissionAuthority,
recordEvidence,
});
+ registerElectronTools(server, {
+ logger: toolLogger,
+ electron: options.electronObservation,
+ permissionAuthority: options.permissionAuthority,
+ recordEvidence,
+ });
registerGuidedPrompts(server, analysis, session);
if (session !== undefined) {
registerEvidenceResources(server, session);
diff --git a/src/server/registerBrowserTools.ts b/src/server/registerBrowserTools.ts
index 93e5bb0b8..d88ef4e82 100644
--- a/src/server/registerBrowserTools.ts
+++ b/src/server/registerBrowserTools.ts
@@ -4,14 +4,28 @@ import type { BrowserObservationPort } from "../application/BrowserObservationPo
import type { BinarySessionPort } from "../application/BinarySession.js";
import type { PermissionAuthority } from "../application/PermissionAuthority.js";
import {
+ analyzeWebBundle,
+ captureWebScreenshot,
+ compareWebCaptureEvidence,
+ compareWebScreenshotEvidence,
+ discoverWebMcpTools,
inspectWebPage,
listBrowserTargets,
+ observeWebSession,
} from "../application/BrowserObservationService.js";
import { BROWSER_TOOL_CONTRACTS } from "../contracts/browserToolContracts.js";
import {
inspectWebPageInputSchema,
listBrowserTargetsInputSchema,
} from "../domain/browserObservation.js";
+import { analyzeWebBundleInputSchema } from "../domain/webBundleAnalysis.js";
+import { observeWebSessionInputSchema } from "../domain/browserSession.js";
+import { discoverWebMcpToolsInputSchema } from "../domain/webMcpDiscovery.js";
+import { compareWebCapturesInputSchema } from "../domain/webCaptureDiff.js";
+import {
+ captureWebScreenshotInputSchema,
+ compareWebScreenshotsInputSchema,
+} from "../domain/webScreenshot.js";
import type { Logger } from "../logger.js";
import { logToolExecution } from "./toolLogging.js";
import { toCallToolResult } from "./toolResult.js";
@@ -30,7 +44,16 @@ export const registerBrowserTools = (
server: McpServer,
options: BrowserToolRegistration,
): void => {
- const [listContract, inspectContract] = BROWSER_TOOL_CONTRACTS;
+ const [
+ listContract,
+ inspectContract,
+ analyzeContract,
+ sessionContract,
+ webMcpContract,
+ captureDiffContract,
+ screenshotContract,
+ screenshotDiffContract,
+ ] = BROWSER_TOOL_CONTRACTS;
server.registerTool(
listContract.name,
toolRegistrationOptions(listContract),
@@ -69,6 +92,126 @@ export const registerBrowserTools = (
return evidenceResult(options, inspectContract, result.value);
},
);
+ server.registerTool(
+ analyzeContract.name,
+ toolRegistrationOptions(analyzeContract),
+ async (input, context) => {
+ const parsed = analyzeWebBundleInputSchema.parse(input);
+ const result = await logToolExecution(
+ options.logger,
+ analyzeContract.name,
+ () =>
+ analyzeWebBundle(
+ options.browser,
+ options.permissionAuthority,
+ parsed,
+ {
+ signal: context.mcpReq.signal,
+ progress: mcpProgressReporter(context),
+ },
+ ),
+ );
+ if (!result.ok) return toCallToolResult(result, analyzeContract);
+ return evidenceResult(options, analyzeContract, result.value);
+ },
+ );
+ server.registerTool(
+ sessionContract.name,
+ toolRegistrationOptions(sessionContract),
+ async (input, context) => {
+ const parsed = observeWebSessionInputSchema.parse(input);
+ const result = await logToolExecution(
+ options.logger,
+ sessionContract.name,
+ () =>
+ observeWebSession(
+ options.browser,
+ options.permissionAuthority,
+ parsed,
+ {
+ signal: context.mcpReq.signal,
+ progress: mcpProgressReporter(context),
+ },
+ ),
+ );
+ if (!result.ok) return toCallToolResult(result, sessionContract);
+ return evidenceResult(options, sessionContract, result.value);
+ },
+ );
+ server.registerTool(
+ webMcpContract.name,
+ toolRegistrationOptions(webMcpContract),
+ async (input, context) => {
+ const parsed = discoverWebMcpToolsInputSchema.parse(input);
+ const result = await logToolExecution(
+ options.logger,
+ webMcpContract.name,
+ () =>
+ discoverWebMcpTools(
+ options.browser,
+ options.permissionAuthority,
+ parsed,
+ {
+ signal: context.mcpReq.signal,
+ progress: mcpProgressReporter(context),
+ },
+ ),
+ );
+ if (!result.ok) return toCallToolResult(result, webMcpContract);
+ return evidenceResult(options, webMcpContract, result.value);
+ },
+ );
+ server.registerTool(
+ captureDiffContract.name,
+ toolRegistrationOptions(captureDiffContract),
+ async (input) => {
+ const parsed = compareWebCapturesInputSchema.parse(input);
+ const result = await logToolExecution(
+ options.logger,
+ captureDiffContract.name,
+ () => compareWebCaptureEvidence(options.browser, parsed),
+ );
+ if (!result.ok) return toCallToolResult(result, captureDiffContract);
+ return evidenceResult(options, captureDiffContract, result.value);
+ },
+ );
+ server.registerTool(
+ screenshotContract.name,
+ toolRegistrationOptions(screenshotContract),
+ async (input, context) => {
+ const parsed = captureWebScreenshotInputSchema.parse(input);
+ const result = await logToolExecution(
+ options.logger,
+ screenshotContract.name,
+ () =>
+ captureWebScreenshot(
+ options.browser,
+ options.permissionAuthority,
+ parsed,
+ {
+ signal: context.mcpReq.signal,
+ progress: mcpProgressReporter(context),
+ },
+ ),
+ );
+ if (!result.ok) return toCallToolResult(result, screenshotContract);
+ return evidenceResult(options, screenshotContract, result.value);
+ },
+ );
+ server.registerTool(
+ screenshotDiffContract.name,
+ toolRegistrationOptions(screenshotDiffContract),
+ async (input) => {
+ const parsed = compareWebScreenshotsInputSchema.parse(input);
+ const result = await logToolExecution(
+ options.logger,
+ screenshotDiffContract.name,
+ () => compareWebScreenshotEvidence(options.browser, parsed),
+ );
+ if (!result.ok) return toCallToolResult(result, screenshotDiffContract);
+ return evidenceResult(options, screenshotDiffContract, result.value);
+ },
+ );
};
const evidenceResult = (
diff --git a/src/server/registerElectronTools.ts b/src/server/registerElectronTools.ts
new file mode 100644
index 000000000..edec00c84
--- /dev/null
+++ b/src/server/registerElectronTools.ts
@@ -0,0 +1,90 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+
+import type { BinarySessionPort } from "../application/BinarySession.js";
+import type { ElectronObservationPort } from "../application/ElectronObservationPort.js";
+import {
+ inspectElectronPage,
+ listElectronTargets,
+} from "../application/ElectronObservationService.js";
+import type { PermissionAuthority } from "../application/PermissionAuthority.js";
+import { ELECTRON_TOOL_CONTRACTS } from "../contracts/electronToolContracts.js";
+import {
+ inspectElectronPageInputSchema,
+ listElectronTargetsInputSchema,
+} from "../domain/electronObservation.js";
+import type { Logger } from "../logger.js";
+import { logToolExecution } from "./toolLogging.js";
+import { toCallToolResult } from "./toolResult.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { mcpProgressReporter } from "./mcpProgress.js";
+
+interface ElectronToolRegistration {
+ readonly logger: Logger;
+ readonly electron: ElectronObservationPort | undefined;
+ readonly permissionAuthority: PermissionAuthority | undefined;
+ readonly recordEvidence: BinarySessionPort["recordEvidence"] | undefined;
+}
+
+/** Register Electron tools even when provider or permission policy is absent. */
+export const registerElectronTools = (
+ server: McpServer,
+ options: ElectronToolRegistration,
+): void => {
+ const [listContract, inspectContract] = ELECTRON_TOOL_CONTRACTS;
+ server.registerTool(
+ listContract.name,
+ toolRegistrationOptions(listContract),
+ async (input, context) => {
+ const parsed = listElectronTargetsInputSchema.parse(input);
+ const result = await logToolExecution(
+ options.logger,
+ listContract.name,
+ () =>
+ listElectronTargets(
+ options.electron,
+ options.permissionAuthority,
+ parsed,
+ { signal: context.mcpReq.signal },
+ ),
+ );
+ if (!result.ok) return toCallToolResult(result, listContract);
+ return evidenceResult(options, listContract, result.value);
+ },
+ );
+ server.registerTool(
+ inspectContract.name,
+ toolRegistrationOptions(inspectContract),
+ async (input, context) => {
+ const parsed = inspectElectronPageInputSchema.parse(input);
+ const result = await logToolExecution(
+ options.logger,
+ inspectContract.name,
+ () =>
+ inspectElectronPage(
+ options.electron,
+ options.permissionAuthority,
+ parsed,
+ {
+ signal: context.mcpReq.signal,
+ progress: mcpProgressReporter(context),
+ },
+ ),
+ );
+ if (!result.ok) return toCallToolResult(result, inspectContract);
+ return evidenceResult(options, inspectContract, result.value);
+ },
+ );
+};
+
+const evidenceResult = (
+ options: ElectronToolRegistration,
+ contract: (typeof ELECTRON_TOOL_CONTRACTS)[number],
+ evidence: import("../domain/evidence.js").Evidence,
+) => {
+ const recorded = options.recordEvidence?.(evidence);
+ return recorded !== undefined && !recorded.ok
+ ? toCallToolResult(recorded, contract)
+ : toCallToolResult({ ok: true, value: evidence }, contract, {
+ evidenceResourcesAvailable: recorded !== undefined,
+ });
+};
diff --git a/src/server/registerSessionStatusTool.ts b/src/server/registerSessionStatusTool.ts
index aba0a6f7d..6a498ce47 100644
--- a/src/server/registerSessionStatusTool.ts
+++ b/src/server/registerSessionStatusTool.ts
@@ -20,6 +20,7 @@ export const registerSessionStatusTool = (
readonly processCaptureEnabled: boolean;
readonly evidenceFileRoots: number;
readonly browserObservationEnabled?: boolean;
+ readonly electronObservationEnabled?: boolean;
},
): void => {
server.registerTool(
diff --git a/src/server/registerSessionTools.ts b/src/server/registerSessionTools.ts
index 557be110c..f4bbe946f 100644
--- a/src/server/registerSessionTools.ts
+++ b/src/server/registerSessionTools.ts
@@ -438,6 +438,7 @@ interface LifecycleToolRegistration {
readonly processCaptureEnabled: boolean;
readonly evidenceFileRoots: number;
readonly browserObservationEnabled?: boolean;
+ readonly electronObservationEnabled?: boolean;
};
readonly permissionAuthority?: PermissionAuthority;
}
@@ -599,6 +600,7 @@ export interface SessionToolOptions {
readonly processCaptureEnabled: boolean;
readonly evidenceFileRoots: number;
readonly browserObservationEnabled?: boolean;
+ readonly electronObservationEnabled?: boolean;
};
}
@@ -646,6 +648,7 @@ export const registerSessionTools = (
processCaptureEnabled: processPolicy.enabled,
evidenceFileRoots: evidenceFilePolicy.roots.length,
browserObservationEnabled: false,
+ electronObservationEnabled: false,
})),
...(options.permissionAuthority === undefined
? {}
diff --git a/tests/browserCli.test.ts b/tests/browserCli.test.ts
index 6d4177bd4..36880527a 100644
--- a/tests/browserCli.test.ts
+++ b/tests/browserCli.test.ts
@@ -10,7 +10,7 @@ import {
const execute = promisify(execFile);
const browsers: FakeCdpBrowser[] = [];
-const INTEGRATION_TEST_TIMEOUT_MS = 20_000;
+const INTEGRATION_TEST_TIMEOUT_MS = 40_000;
afterEach(async () => {
await Promise.all(browsers.splice(0).map(async (browser) => browser.close()));
@@ -20,7 +20,11 @@ describe("browser CLI parity", () => {
it(
"returns the same Evidence v2 discovery and inspection contracts",
async () => {
- const browser = await startFakeCdpBrowser();
+ const browser = await startFakeCdpBrowser({
+ sessionTimeline: "same_origin",
+ webMcpTools: true,
+ sensitiveShapes: true,
+ });
browsers.push(browser);
const environment = {
...process.env,
@@ -49,6 +53,12 @@ describe("browser CLI parity", () => {
"--approved",
"--observation-ms",
"0",
+ "--include-console-text",
+ "--console-text-approved",
+ "--include-json-body-shapes",
+ "--json-body-schema-approved",
+ "--include-websocket-shapes",
+ "--websocket-shape-approved",
"--json",
],
environment,
@@ -58,9 +68,122 @@ describe("browser CLI parity", () => {
provider: { id: "rea-cdp-browser" },
normalized_result: {
target: { target_id: "allowed-page" },
- network: { prior_activity_available: false },
+ network: {
+ prior_activity_available: false,
+ requests: [
+ expect.objectContaining({
+ body_shapes: expect.objectContaining({ status: "included" }),
+ }),
+ ],
+ },
},
});
+ const inspection = normalizedResult(inspected);
+ const compared = await runCli(
+ [
+ "compare-web-captures",
+ JSON.stringify({ inspection }),
+ JSON.stringify({ inspection }),
+ "--json",
+ ],
+ environment,
+ );
+ expect(compared).toMatchObject({
+ operation: "compare_web_captures",
+ normalized_result: {
+ overall_status: "unknown",
+ dimensions: {
+ network: { status: "unknown", total_changes: 0 },
+ },
+ },
+ });
+ const analyzed = await runCli(
+ [
+ "analyze-web-bundle",
+ browser.endpoint,
+ "allowed-page",
+ "--approved",
+ "--source-capture-approved",
+ "--observation-ms",
+ "0",
+ "--json",
+ ],
+ environment,
+ );
+ expect(analyzed).toMatchObject({
+ operation: "analyze_web_bundle",
+ normalized_result: {
+ capture: { scripts_analyzed: 1 },
+ observations: { source_maps: { status: "not_requested" } },
+ },
+ });
+ const observedSession = await runCli(
+ [
+ "observe-web-session",
+ browser.endpoint,
+ "allowed-page",
+ "--approved",
+ "--observation-ms",
+ "5",
+ "--json",
+ ],
+ environment,
+ );
+ expect(observedSession).toMatchObject({
+ operation: "observe_web_session",
+ normalized_result: {
+ window: { end_reason: "window_elapsed" },
+ timeline: expect.arrayContaining([
+ expect.objectContaining({ type: "same_origin_reload" }),
+ ]),
+ },
+ });
+ const webMcp = await runCli(
+ [
+ "discover-webmcp-tools",
+ browser.endpoint,
+ "allowed-page",
+ "--approved",
+ "--observation-ms",
+ "0",
+ "--json",
+ ],
+ environment,
+ );
+ expect(webMcp).toMatchObject({
+ operation: "discover_webmcp_tools",
+ normalized_result: {
+ tools: {
+ items: [expect.objectContaining({ name: "search_orders" })],
+ },
+ },
+ });
+ const screenshot = await runCli(
+ [
+ "capture-web-screenshot",
+ browser.endpoint,
+ "allowed-page",
+ "--approved",
+ "--screenshot-approved",
+ "--json",
+ ],
+ environment,
+ );
+ const artifact = screenshotArtifact(screenshot);
+ expect(artifact).toMatchObject({ media_type: "image/png", bytes: 70 });
+ const visual = await runCli(
+ [
+ "compare-web-screenshots",
+ JSON.stringify(artifact),
+ JSON.stringify(artifact),
+ "--json",
+ ],
+ environment,
+ );
+ expect(visual).toMatchObject({
+ operation: "compare_web_screenshots",
+ normalized_result: { status: "identical", changed_pixels: 0 },
+ });
const policy = await runCli(
[
"policy",
@@ -137,3 +260,22 @@ const runCli = async (
throw cause;
}
};
+
+const screenshotArtifact = (value: unknown): Record => {
+ if (
+ !isRecord(value) ||
+ !isRecord(value.normalized_result) ||
+ !isRecord(value.normalized_result.artifact)
+ )
+ throw new TypeError("Missing CLI screenshot artifact");
+ return value.normalized_result.artifact;
+};
+
+const normalizedResult = (value: unknown): Record => {
+ if (!isRecord(value) || !isRecord(value.normalized_result))
+ throw new TypeError("Missing CLI normalized result");
+ return value.normalized_result;
+};
+
+const isRecord = (value: unknown): value is Record =>
+ typeof value === "object" && value !== null && !Array.isArray(value);
diff --git a/tests/browserMcp.test.ts b/tests/browserMcp.test.ts
index 948711765..cfc781f2c 100644
--- a/tests/browserMcp.test.ts
+++ b/tests/browserMcp.test.ts
@@ -27,14 +27,29 @@ describe("browser MCP tools", () => {
it(
"exposes CLI-equivalent Evidence v2 and session resources",
async () => {
- const browser = await startFakeCdpBrowser();
+ const browser = await startFakeCdpBrowser({
+ sessionTimeline: "same_origin",
+ webMcpTools: true,
+ sensitiveShapes: true,
+ });
browsers.push(browser);
const connected = await connectBrowser(browser);
const tools = await connected.client.listTools();
- expect(tools.tools).toHaveLength(70);
+ expect(tools.tools).toHaveLength(78);
expect(tools.tools.map(({ name }) => name)).toEqual(
- expect.arrayContaining(["list_browser_targets", "inspect_web_page"]),
+ expect.arrayContaining([
+ "list_browser_targets",
+ "inspect_web_page",
+ "analyze_web_bundle",
+ "observe_web_session",
+ "discover_webmcp_tools",
+ "compare_web_captures",
+ "capture_web_screenshot",
+ "compare_web_screenshots",
+ "list_electron_targets",
+ "inspect_electron_page",
+ ]),
);
const status = await connected.client.callTool({
name: "binary_session",
@@ -65,7 +80,7 @@ describe("browser MCP tools", () => {
authority: "external-service",
confidence: "observed",
subject: null,
- provider: { id: "rea-cdp-browser", version: "1" },
+ provider: { id: "rea-cdp-browser", version: "2" },
normalized_result: {
targets: { items: [{ target_id: "allowed-page" }] },
},
@@ -78,6 +93,12 @@ describe("browser MCP tools", () => {
target_id: "allowed-page",
approved: true,
observation_ms: 0,
+ include_console_text: true,
+ console_text_approved: true,
+ include_json_body_shapes: true,
+ json_body_schema_approved: true,
+ include_websocket_shapes: true,
+ websocket_shape_approved: true,
},
});
expect(inspected.isError).not.toBe(true);
@@ -85,10 +106,112 @@ describe("browser MCP tools", () => {
operation: "inspect_web_page",
normalized_result: {
target: { target_id: "allowed-page" },
- network: { prior_activity_available: false },
console: { prior_activity_available: false },
+ network: {
+ prior_activity_available: false,
+ requests: [
+ expect.objectContaining({
+ body_shapes: expect.objectContaining({ status: "included" }),
+ }),
+ ],
+ },
},
});
+ const analyzed = await connected.client.callTool({
+ name: "analyze_web_bundle",
+ arguments: {
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ source_capture_approved: true,
+ observation_ms: 0,
+ },
+ });
+ expect(analyzed.isError).not.toBe(true);
+ expect(analyzed.structuredContent).toMatchObject({
+ operation: "analyze_web_bundle",
+ normalized_result: {
+ capture: { scripts_analyzed: 1 },
+ observations: { source_maps: { status: "not_requested" } },
+ },
+ });
+ const observedSession = await connected.client.callTool({
+ name: "observe_web_session",
+ arguments: {
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 5,
+ },
+ });
+ expect(observedSession.isError).not.toBe(true);
+ expect(observedSession.structuredContent).toMatchObject({
+ operation: "observe_web_session",
+ normalized_result: {
+ window: { end_reason: "window_elapsed" },
+ timeline: expect.arrayContaining([
+ expect.objectContaining({ type: "same_origin_reload" }),
+ ]),
+ },
+ });
+ const webMcp = await connected.client.callTool({
+ name: "discover_webmcp_tools",
+ arguments: {
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 0,
+ },
+ });
+ expect(webMcp.isError).not.toBe(true);
+ expect(webMcp.structuredContent).toMatchObject({
+ operation: "discover_webmcp_tools",
+ normalized_result: {
+ tools: {
+ items: [expect.objectContaining({ name: "search_orders" })],
+ },
+ },
+ });
+ const capture = normalizedResultOf(inspected.structuredContent);
+ const compared = await connected.client.callTool({
+ name: "compare_web_captures",
+ arguments: {
+ before: { inspection: capture },
+ after: { inspection: capture },
+ },
+ });
+ expect(compared.isError).not.toBe(true);
+ expect(compared.structuredContent).toMatchObject({
+ operation: "compare_web_captures",
+ normalized_result: { overall_status: "unknown" },
+ });
+ const screenshot = await connected.client.callTool({
+ name: "capture_web_screenshot",
+ arguments: {
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ screenshot_approved: true,
+ },
+ });
+ expect(screenshot.isError).not.toBe(true);
+ const screenshotArtifact = artifactOf(screenshot.structuredContent);
+ const visual = await connected.client.callTool({
+ name: "compare_web_screenshots",
+ arguments: {
+ before: screenshotArtifact,
+ after: screenshotArtifact,
+ },
+ });
+ expect(visual.isError).not.toBe(true);
+ expect(visual.structuredContent).toMatchObject({
+ operation: "compare_web_screenshots",
+ normalized_result: { status: "identical", changed_pixels: 0 },
+ });
const evidenceId = evidenceIdOf(inspected.structuredContent);
const evidence = await connected.client.readResource({
uri: `rea://evidence/${evidenceId}`,
@@ -168,3 +291,24 @@ const evidenceIdOf = (value: unknown): string => {
throw new TypeError("Missing browser evidence ID");
return value.evidence_id;
};
+
+const normalizedResultOf = (value: unknown): unknown => {
+ if (
+ typeof value !== "object" ||
+ value === null ||
+ !("normalized_result" in value)
+ )
+ throw new TypeError("Missing normalized browser result");
+ return value.normalized_result;
+};
+
+const artifactOf = (value: unknown): unknown => {
+ const normalized = normalizedResultOf(value);
+ if (
+ typeof normalized !== "object" ||
+ normalized === null ||
+ !("artifact" in normalized)
+ )
+ throw new TypeError("Missing screenshot artifact");
+ return normalized.artifact;
+};
diff --git a/tests/browserObservation.test.ts b/tests/browserObservation.test.ts
index 2d6d41fa6..29cb36c20 100644
--- a/tests/browserObservation.test.ts
+++ b/tests/browserObservation.test.ts
@@ -7,6 +7,7 @@ import {
listBrowserTargetsInputSchema,
sanitizeBrowserUrl,
} from "../src/domain/browserObservation.js";
+import { captureWebScreenshotInputSchema } from "../src/domain/webScreenshot.js";
describe("browser observation contracts", () => {
it("normalizes exact HTTP origins without accepting broader URL scopes", () => {
@@ -66,12 +67,21 @@ describe("browser observation contracts", () => {
}),
).toMatchObject({
observation_ms: 500,
+ include_accessibility_text: false,
+ include_console_text: false,
+ console_text_approved: false,
+ include_json_body_shapes: false,
+ json_body_schema_approved: false,
+ include_websocket_shapes: false,
+ websocket_shape_approved: false,
include_script_sources: false,
include_storage_keys: false,
limits: {
max_frames: 200,
max_dom_nodes: 2_000,
max_ax_nodes: 2_000,
+ max_ax_text_field_bytes: 1_024,
+ max_total_ax_text_bytes: 65_536,
max_scripts: 200,
max_resources: 2_000,
max_workers: 500,
@@ -80,11 +90,54 @@ describe("browser observation contracts", () => {
max_total_script_source_bytes: 4_194_304,
max_network_events: 1_000,
max_console_events: 200,
+ max_console_text_field_bytes: 1_024,
+ max_total_console_text_bytes: 65_536,
+ max_json_body_bytes: 1_048_576,
+ max_total_json_body_bytes: 4_194_304,
+ max_json_shape_nodes: 5_000,
+ max_json_shape_depth: 20,
max_websocket_events: 500,
+ max_websocket_shape_bytes: 65_536,
+ max_total_websocket_shape_bytes: 1_048_576,
},
});
});
+ it("requires independent approval for each sensitive capture surface", () => {
+ const base = {
+ cdp_endpoint: "http://127.0.0.1:9222",
+ allowed_origins: ["https://app.example.test"],
+ target_id: "page-1",
+ approved: true,
+ };
+ for (const input of [
+ { include_console_text: true },
+ { include_json_body_shapes: true },
+ { include_websocket_shapes: true },
+ ])
+ expect(
+ inspectWebPageInputSchema.safeParse({ ...base, ...input }).success,
+ ).toBe(false);
+ });
+
+ it("requires an independent literal approval for screenshot pixels", () => {
+ const input = {
+ cdp_endpoint: "http://127.0.0.1:9222",
+ allowed_origins: ["https://app.example.test"],
+ target_id: "page-1",
+ approved: true,
+ };
+ expect(captureWebScreenshotInputSchema.safeParse(input).success).toBe(
+ false,
+ );
+ expect(
+ captureWebScreenshotInputSchema.safeParse({
+ ...input,
+ screenshot_approved: true,
+ }).success,
+ ).toBe(true);
+ });
+
it("removes credentials, query values, and fragments from observed URLs", () => {
expect(
sanitizeBrowserUrl(
diff --git a/tests/cdpBrowserProvider.test.ts b/tests/cdpBrowserProvider.test.ts
index 26d266323..a624bd32c 100644
--- a/tests/cdpBrowserProvider.test.ts
+++ b/tests/cdpBrowserProvider.test.ts
@@ -6,6 +6,10 @@ import {
listBrowserTargetsInputSchema,
webPageInspectionSchema,
} from "../src/domain/browserObservation.js";
+import { analyzeWebBundleInputSchema } from "../src/domain/webBundleAnalysis.js";
+import { observeWebSessionInputSchema } from "../src/domain/browserSession.js";
+import { discoverWebMcpToolsInputSchema } from "../src/domain/webMcpDiscovery.js";
+import { captureWebScreenshotInputSchema } from "../src/domain/webScreenshot.js";
import {
startFakeCdpBrowser,
type FakeCdpBrowser,
@@ -72,32 +76,92 @@ describe("CdpBrowserProvider", () => {
expect(() => webPageInspectionSchema.parse(result.value)).not.toThrow();
expect(result.value.frames).toHaveLength(1);
expect(result.value.dom.nodes).toHaveLength(2);
- expect(result.value.dom.nodes[1]?.attribute_names).toEqual(["token"]);
- expect(result.value.accessibility.nodes[0]?.name).toBe("Submit report");
+ expect(result.value.dom.nodes[1]?.attribute_names).toEqual([
+ "token",
+ "href",
+ "rel",
+ ]);
+ expect(result.value.accessibility).toMatchObject({
+ text_capture: {
+ status: "not_approved",
+ retained_bytes: 0,
+ },
+ nodes: [expect.objectContaining({ name: null, description: null })],
+ });
expect(result.value.scripts.items).toHaveLength(1);
- expect(result.value.scripts.items[0]?.script_id).toBe("script-allowed");
+ expect(result.value.scripts.items[0]?.script_key).toMatch(
+ /^scr_[a-f0-9]{64}$/u,
+ );
+ expect(result.value.scripts.items[0]?.resource_reconciliation).toEqual({
+ status: "exact",
+ resource_key: result.value.resources[0]?.resource_key,
+ });
expect(result.value.scripts.items[0]?.source).toEqual({
included: false,
reason: "source capture was not approved",
});
expect(result.value.resources).toHaveLength(1);
expect(result.value.network.requests).toHaveLength(1);
+ expect(result.value.network.requests[0]?.initiator).toEqual({
+ type: "script",
+ url: `${browser.allowedOrigin}/app.js?caller=%5BREDACTED%5D`,
+ line: 3,
+ column: 5,
+ });
expect(result.value.network.websocket_events).toEqual([
{
request_id: "websocket-1",
direction: "sent",
opcode: 1,
payload_bytes: Buffer.byteLength("websocket-secret"),
+ payload_shape: null,
},
{
request_id: "websocket-1",
direction: "received",
opcode: 2,
payload_bytes: 3,
+ payload_shape: null,
},
]);
expect(result.value.console.events[0]?.argument_types).toEqual(["string"]);
expect(result.value.workers).toHaveLength(1);
+ expect(result.value.metadata).toMatchObject({
+ headers_allowlisted: true,
+ responses: [
+ {
+ content_length: 321,
+ content_encoding: "br",
+ csp: { nonce_count: 1, hash_count: 1 },
+ policies: {
+ coop: "same-origin",
+ coep: "require-corp",
+ permissions_policy_features: ["camera", "geolocation"],
+ },
+ },
+ ],
+ dom_urls: [
+ {
+ attribute: "href",
+ url: `${browser.allowedOrigin}/agent?token=%5BREDACTED%5D`,
+ destination_scope: "approved",
+ },
+ ],
+ agent_hints: expect.arrayContaining([
+ expect.objectContaining({
+ mechanism: "link_rel",
+ declaration: "mcp service-desc",
+ }),
+ expect.objectContaining({
+ mechanism: "dom_link_rel",
+ declaration: "mcp",
+ }),
+ expect.objectContaining({
+ mechanism: "response_header",
+ declaration: "x-model-context",
+ }),
+ ]),
+ });
expect(result.value.storage).toEqual(
expect.objectContaining({
local_storage_keys: ["public-key"],
@@ -121,6 +185,7 @@ describe("CdpBrowserProvider", () => {
"request-secret",
"request-body-secret",
"response-secret",
+ "response-body-secret",
"websocket-secret",
"websocket-url-secret",
"console-secret",
@@ -128,6 +193,11 @@ describe("CdpBrowserProvider", () => {
"unknown-console-value-secret",
"storage-secret",
"secret-id",
+ "dom-url-secret",
+ "link-secret",
+ "csp-secret",
+ "hash-secret",
+ "header-secret",
])
expect(serialized).not.toContain(secret);
const methods = browser.commands.map((command) => command.method);
@@ -135,6 +205,218 @@ describe("CdpBrowserProvider", () => {
expect(methods).not.toContain("Browser.close");
expect(methods).not.toContain("Target.closeTarget");
expect(methods).not.toContain("Runtime.evaluate");
+ expect(methods).not.toContain("Network.getResponseBody");
+ });
+
+ it("captures only approved redacted console text and value-free payload shapes", async () => {
+ const browser = await startFakeCdpBrowser({
+ sensitiveShapes: true,
+ binaryWebSocketEvent: true,
+ });
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().inspectPage(
+ inspectWebPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 0,
+ include_console_text: true,
+ console_text_approved: true,
+ include_json_body_shapes: true,
+ json_body_schema_approved: true,
+ include_websocket_shapes: true,
+ websocket_shape_approved: true,
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ expect(result.value.console.events[0]?.text_capture).toEqual({
+ status: "included",
+ values: [
+ { argument_index: 0, type: "string", text: "authorization=[REDACTED]" },
+ { argument_index: 1, type: "number", text: "42" },
+ ],
+ retained_bytes: 26,
+ truncated_values: 0,
+ });
+ expect(result.value.network.requests[0]?.body_shapes).toMatchObject({
+ status: "included",
+ request: {
+ root_type: "object",
+ properties: expect.arrayContaining([
+ expect.objectContaining({ path: "/token", types: ["string"] }),
+ expect.objectContaining({
+ path: "/filters/active",
+ types: ["boolean"],
+ }),
+ ]),
+ },
+ response: {
+ root_type: "object",
+ properties: expect.arrayContaining([
+ expect.objectContaining({
+ path: "/result/token",
+ types: ["string"],
+ }),
+ expect.objectContaining({ path: "/items/*/id", types: ["number"] }),
+ ]),
+ },
+ });
+ expect(result.value.network.websocket_events).toEqual([
+ expect.objectContaining({
+ opcode: 1,
+ payload_shape: expect.objectContaining({
+ format: "json",
+ json_shape: expect.objectContaining({
+ properties: expect.arrayContaining([
+ expect.objectContaining({ path: "/token", types: ["string"] }),
+ ]),
+ }),
+ }),
+ }),
+ expect.objectContaining({
+ opcode: 2,
+ payload_shape: {
+ format: "binary",
+ json_shape: null,
+ truncated: false,
+ },
+ }),
+ ]);
+ const serialized = JSON.stringify(result.value);
+ for (const secret of [
+ "request-body-secret",
+ "response-body-secret",
+ "websocket-secret",
+ "console-secret",
+ "object-secret",
+ ])
+ expect(serialized).not.toContain(secret);
+ const methods = browser.commands.map(({ method }) => method);
+ expect(methods).toContain("Network.getResponseBody");
+ expect(methods).not.toContain("Runtime.getProperties");
+ expect(methods).not.toContain("Runtime.callFunctionOn");
+ });
+
+ it("reports independent sensitive-capture truncation at aggregate byte limits", async () => {
+ const browser = await startFakeCdpBrowser({ sensitiveShapes: true });
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().inspectPage(
+ inspectWebPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 0,
+ include_console_text: true,
+ console_text_approved: true,
+ include_json_body_shapes: true,
+ json_body_schema_approved: true,
+ include_websocket_shapes: true,
+ websocket_shape_approved: true,
+ limits: {
+ max_console_text_field_bytes: 5,
+ max_total_console_text_bytes: 5,
+ max_json_body_bytes: 10,
+ max_total_json_body_bytes: 10,
+ max_websocket_shape_bytes: 5,
+ max_total_websocket_shape_bytes: 5,
+ },
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ expect(result.value.console.events[0]?.text_capture).toEqual({
+ status: "truncated",
+ values: [{ argument_index: 0, type: "string", text: "autho" }],
+ retained_bytes: 5,
+ truncated_values: 2,
+ });
+ expect(result.value.network.requests[0]?.body_shapes.status).toBe(
+ "truncated",
+ );
+ expect(result.value.network.websocket_events[0]?.payload_shape).toEqual({
+ format: "text",
+ json_shape: null,
+ truncated: true,
+ });
+ expect(result.value.completeness.truncated_sections).toEqual(
+ expect.arrayContaining([
+ "console_text",
+ "json_body_shapes",
+ "websocket_shapes",
+ ]),
+ );
+ });
+
+ it("fails closed on malformed approved response and binary payload encodings", async () => {
+ const browser = await startFakeCdpBrowser({
+ invalidResponseBodyBase64: true,
+ binaryWebSocketEvent: true,
+ invalidBinaryWebSocketEvent: true,
+ });
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().inspectPage(
+ inspectWebPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 0,
+ include_json_body_shapes: true,
+ json_body_schema_approved: true,
+ include_websocket_shapes: true,
+ websocket_shape_approved: true,
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ expect(result.value.network.requests[0]?.body_shapes).toMatchObject({
+ status: "partial",
+ request: expect.any(Object),
+ response: null,
+ });
+ expect(result.value.network.websocket_events[1]).toMatchObject({
+ opcode: 2,
+ payload_bytes: 0,
+ payload_shape: { format: "binary", json_shape: null },
+ });
+ expect(result.value.completeness.unavailable_sections).toEqual(
+ expect.arrayContaining(["json_body_shapes", "websocket_frames"]),
+ );
+ });
+
+ it("captures bounded accessibility text only after independent approval", async () => {
+ const browser = await startFakeCdpBrowser();
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().inspectPage(
+ inspectWebPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 0,
+ include_accessibility_text: true,
+ limits: {
+ max_ax_text_field_bytes: 6,
+ max_total_ax_text_bytes: 6,
+ },
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ expect(result.value.accessibility).toMatchObject({
+ text_capture: {
+ status: "truncated",
+ retained_bytes: 6,
+ truncated_fields: 2,
+ },
+ nodes: [expect.objectContaining({ name: "Submit" })],
+ });
+ expect(result.value.completeness.truncated_sections).toContain(
+ "accessibility",
+ );
});
it("drops network evidence when a request redirects outside the approved origin", async () => {
@@ -175,8 +457,11 @@ describe("CdpBrowserProvider", () => {
expect(result.value.scripts.items[0]?.source).toEqual(
expect.objectContaining({
included: true,
- content: "export const observed = 'source-secret';",
- bytes: 40,
+ artifact: expect.objectContaining({
+ text: "export const observed = 'source-secret';",
+ bytes: 40,
+ uri: expect.stringMatching(/^rea:\/\/web-content\/sha256\//u),
+ }),
}),
);
expect(browser.commands.map((command) => command.method)).toContain(
@@ -184,6 +469,380 @@ describe("CdpBrowserProvider", () => {
);
});
+ it("fetches and validates source maps only after separate approval", async () => {
+ const browser = await startFakeCdpBrowser({
+ sourceMapBody: JSON.stringify({
+ version: 3,
+ names: [],
+ sources: ["src/main.ts"],
+ sourcesContent: ["export const original = true;"],
+ mappings: "AAAA",
+ }),
+ });
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().analyzeBundle(
+ analyzeWebBundleInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ source_capture_approved: true,
+ observation_ms: 0,
+ fetch_source_maps: true,
+ source_map_fetch_approved: true,
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ expect(result.value.observations.source_maps).toMatchObject({
+ status: "included",
+ items: [
+ {
+ status: "included",
+ original_sources: [
+ expect.objectContaining({
+ source: `${browser.allowedOrigin}/src/main.ts`,
+ }),
+ ],
+ mappings: [expect.any(Object)],
+ },
+ ],
+ });
+ const sourceMapRequest = browser.httpRequests.find(({ url }) =>
+ url.startsWith("/app.js.map"),
+ );
+ expect(sourceMapRequest).toEqual({
+ url: "/app.js.map?token=map-secret",
+ authorization: undefined,
+ cookie: undefined,
+ referer: undefined,
+ });
+ });
+
+ it("observes user-driven reload, SPA, redirect, failure, and lifecycle events", async () => {
+ const browser = await startFakeCdpBrowser({
+ sessionTimeline: "same_origin",
+ });
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().observeSession(
+ observeWebSessionInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 20,
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ expect(result.value.window.end_reason).toBe("window_elapsed");
+ expect(result.value.timeline.map(({ type }) => type)).toEqual([
+ "navigation_requested",
+ "same_origin_reload",
+ "same_document_navigation",
+ "redirect",
+ "load_failed",
+ "lifecycle",
+ ]);
+ expect(result.value.timeline).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ type: "same_document_navigation",
+ url: `${browser.allowedOrigin}/reloaded?token=%5BREDACTED%5D`,
+ }),
+ expect.objectContaining({
+ type: "load_failed",
+ detail: "net::ERR_CONNECTION_REFUSED",
+ }),
+ ]),
+ );
+ expect(result.value.completeness.status).toBe("attach_limited");
+ expect(JSON.stringify(result.value)).not.toContain("session-secret");
+ expect(JSON.stringify(result.value)).not.toContain("redirect-secret");
+ expect(browser.commands.map(({ method }) => method)).toContain(
+ "Target.detachFromTarget",
+ );
+ });
+
+ it("discovers untrusted WebMCP declarations without registering or invoking them", async () => {
+ const browser = await startFakeCdpBrowser({ webMcpTools: true });
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().discoverWebMcpTools(
+ discoverWebMcpToolsInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 0,
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ expect(result.value).toMatchObject({
+ status: "available",
+ tools: {
+ total: 1,
+ items: [
+ {
+ name: "search_orders",
+ description: "Search orders; authorization=[REDACTED]",
+ declaration_kind: "declarative",
+ owner_origin: browser.allowedOrigin,
+ annotations: {
+ read_only: true,
+ untrusted_content: true,
+ autosubmit: false,
+ },
+ trust: "page-declared-untrusted",
+ registration_source: {
+ url: `${browser.allowedOrigin}/app.js?token=%5BREDACTED%5D`,
+ line: 12,
+ column: 4,
+ },
+ },
+ ],
+ },
+ });
+ const serialized = JSON.stringify(result.value);
+ for (const secret of [
+ "tool-secret",
+ "schema-secret",
+ "tool-source-secret",
+ "private-tool-secret",
+ ])
+ expect(serialized).not.toContain(secret);
+ const methods = browser.commands.map(({ method }) => method);
+ expect(methods).toContain("WebMCP.enable");
+ expect(methods).not.toContain("WebMCP.invokeTool");
+ expect(methods).not.toContain("Runtime.evaluate");
+ });
+
+ it("reports WebMCP unavailable when the experimental domain is absent", async () => {
+ const browser = await startFakeCdpBrowser({
+ unsupportedMethods: ["WebMCP.enable"],
+ });
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().discoverWebMcpTools(
+ discoverWebMcpToolsInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 0,
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ expect(result.value.status).toBe("unavailable");
+ expect(result.value.tools.items).toEqual([]);
+ expect(result.value.completeness.unavailable_sections).toContain(
+ "webmcp_tools",
+ );
+ });
+
+ it("rejects WebMCP evidence when the page leaves its approved origin", async () => {
+ const browser = await startFakeCdpBrowser({
+ webMcpTools: true,
+ frameUrlAfterFirstRead: "https://private.example.test/tools",
+ });
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().discoverWebMcpTools(
+ discoverWebMcpToolsInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 0,
+ }),
+ );
+
+ expect(result).toMatchObject({
+ ok: false,
+ error: {
+ _tag: "BrowserObservationError",
+ operation: "discover_webmcp_tools",
+ reason: "target_not_allowed",
+ },
+ });
+ expect(browser.commands.map(({ method }) => method)).not.toContain(
+ "WebMCP.invokeTool",
+ );
+ });
+
+ it("bounds WebMCP registration replay and reports dropped declarations", async () => {
+ const browser = await startFakeCdpBrowser({
+ webMcpTools: true,
+ extraCollections: true,
+ });
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().discoverWebMcpTools(
+ discoverWebMcpToolsInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 0,
+ max_tools: 1,
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ expect(result.value.tools).toMatchObject({
+ total: 2,
+ items: [expect.any(Object)],
+ });
+ expect(result.value.completeness).toMatchObject({
+ status: "truncated",
+ dropped_events: { webmcp_tools: 1 },
+ });
+ });
+
+ it("removes WebMCP declarations after their child frame leaves scope", async () => {
+ const browser = await startFakeCdpBrowser({
+ webMcpTools: true,
+ extraCollections: true,
+ webMcpChildLeavesScope: true,
+ });
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().discoverWebMcpTools(
+ discoverWebMcpToolsInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 0,
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ const names = result.value.tools.items.map(({ name }) => name);
+ expect(names).toEqual(
+ expect.arrayContaining(["search_orders", "update_order"]),
+ );
+ expect(names).not.toEqual(
+ expect.arrayContaining(["child_tool", "escaped_child_tool"]),
+ );
+ expect(result.value.completeness.policy_filtered_sections).toContain(
+ "webmcp_tools",
+ );
+ expect(JSON.stringify(result.value)).not.toContain(
+ "cross-origin-child-secret",
+ );
+ });
+
+ it("captures an explicitly approved content-addressed viewport screenshot", async () => {
+ const browser = await startFakeCdpBrowser();
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().captureScreenshot(
+ captureWebScreenshotInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ screenshot_approved: true,
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ expect(result.value).toMatchObject({
+ viewport: { width: 1, height: 1 },
+ artifact: {
+ uri: expect.stringMatching(/^rea:\/\/web-screenshot\/sha256\//u),
+ bytes: 70,
+ media_type: "image/png",
+ },
+ });
+ expect(browser.commands.map(({ method }) => method)).toContain(
+ "Page.captureScreenshot",
+ );
+ });
+
+ it("discards screenshot pixels when the main frame navigates during capture", async () => {
+ const browser = await startFakeCdpBrowser({
+ navigateDuringScreenshotUrl: "https://private.example.test/screenshot",
+ });
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().captureScreenshot(
+ captureWebScreenshotInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ screenshot_approved: true,
+ }),
+ );
+
+ expect(result).toMatchObject({
+ ok: false,
+ error: {
+ _tag: "BrowserObservationError",
+ operation: "capture_web_screenshot",
+ reason: "target_not_allowed",
+ },
+ });
+ });
+
+ it("ends immediately when a redirect leaves policy without exposing its URL", async () => {
+ const browser = await startFakeCdpBrowser({
+ sessionTimeline: "outside_policy",
+ });
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().observeSession(
+ observeWebSessionInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 1_000,
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ expect(result.value.window.end_reason).toBe("target_left_scope");
+ expect(result.value.timeline.at(-1)).toMatchObject({
+ type: "redirect",
+ url: null,
+ destination_scope: "outside_policy",
+ });
+ expect(result.value.completeness).toMatchObject({
+ status: "policy_filtered",
+ policy_filtered_sections: ["timeline"],
+ excluded: [
+ {
+ section: "timeline",
+ reason: "out_of_target_scope",
+ count: 1,
+ },
+ ],
+ });
+ expect(JSON.stringify(result.value)).not.toContain("private.example.test");
+ });
+
+ it("fails closed when the final session frame leaves policy without an event", async () => {
+ const browser = await startFakeCdpBrowser({
+ frameUrlAfterFirstRead: "https://private.example.test/final",
+ });
+ browsers.push(browser);
+ const result = await new CdpBrowserProvider().observeSession(
+ observeWebSessionInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 1,
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ expect(result.value.window.end_reason).toBe("target_left_scope");
+ expect(result.value.target.final_url).toBeNull();
+ expect(result.value.completeness).toMatchObject({
+ status: "policy_filtered",
+ policy_filtered_sections: ["timeline"],
+ });
+ expect(JSON.stringify(result.value)).not.toContain("private.example.test");
+ });
+
it("rejects missing and disallowed page targets before attaching", async () => {
const browser = await startFakeCdpBrowser();
browsers.push(browser);
@@ -354,6 +1013,12 @@ describe("CdpBrowserProvider", () => {
);
if (!degraded.ok) throw degraded.error;
expect(degraded.value.accessibility.nodes).toEqual([]);
+ expect(degraded.value.accessibility.text_capture.status).toBe(
+ "unavailable",
+ );
+ expect(degraded.value.completeness.unavailable_sections).toContain(
+ "accessibility",
+ );
expect(degraded.value.limitations).toContain(
"Accessibility.getFullAXTree was unavailable from this browser target.",
);
diff --git a/tests/cdpCaptureCompleteness.test.ts b/tests/cdpCaptureCompleteness.test.ts
new file mode 100644
index 000000000..7f6e522dc
--- /dev/null
+++ b/tests/cdpCaptureCompleteness.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+
+import { CdpCaptureCompleteness } from "../src/browser/CdpCaptureCompleteness.js";
+
+describe("CdpCaptureCompleteness", () => {
+ it("reports attach-window limitations without claiming a complete history", () => {
+ const capture = new CdpCaptureCompleteness([
+ "network_requests",
+ "console_events",
+ ]);
+
+ expect(capture.snapshot()).toMatchObject({
+ status: "attach_limited",
+ conditions: ["attach_limited"],
+ attach_limited_sections: ["console_events", "network_requests"],
+ excluded: [],
+ dropped_events: { total: 0 },
+ });
+ });
+
+ it("aggregates sparse exclusions and applies explicit status precedence", () => {
+ const capture = new CdpCaptureCompleteness(["network_requests"]);
+ capture.exclude("scripts", "disallowed_origin");
+ capture.exclude("scripts", "disallowed_origin", 2);
+ capture.exclude("storage_keys", "not_approved", null);
+ capture.drop("console_events", 4);
+
+ expect(capture.snapshot()).toMatchObject({
+ status: "truncated",
+ conditions: ["attach_limited", "policy_filtered", "truncated"],
+ policy_filtered_sections: ["scripts", "storage_keys"],
+ truncated_sections: ["console_events"],
+ excluded: [
+ { section: "scripts", reason: "disallowed_origin", count: 3 },
+ { section: "storage_keys", reason: "not_approved", count: null },
+ ],
+ dropped_events: { console_events: 4, total: 4 },
+ });
+ });
+
+ it("restores initial attach limitations when reused for a new capture", () => {
+ const capture = new CdpCaptureCompleteness(["websocket_frames"]);
+ capture.drop("scripts");
+ capture.exclude("resources", "provider_unavailable", null);
+
+ capture.reset();
+
+ expect(capture.snapshot()).toMatchObject({
+ status: "attach_limited",
+ attach_limited_sections: ["websocket_frames"],
+ unavailable_sections: [],
+ excluded: [],
+ dropped_events: { total: 0 },
+ });
+ });
+});
diff --git a/tests/cdpCaptureDocuments.test.ts b/tests/cdpCaptureDocuments.test.ts
index 1df0ec5e5..d1d8a8a79 100644
--- a/tests/cdpCaptureDocuments.test.ts
+++ b/tests/cdpCaptureDocuments.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vitest";
import {
+ captureAccessibility,
captureDom,
captureFrames,
captureResources,
@@ -71,4 +72,65 @@ describe("CDP document capture", () => {
-1, 0, -1, 2,
]);
});
+
+ it("bounds approved accessibility text by UTF-8 bytes without splitting characters", () => {
+ const capture = captureAccessibility(
+ [
+ {
+ nodes: [
+ {
+ nodeId: "node-1",
+ role: { value: "button" },
+ name: { value: "😀a" },
+ description: { value: "éé" },
+ },
+ ],
+ },
+ ],
+ 10,
+ {
+ includeText: true,
+ maximumFieldBytes: 4,
+ maximumTotalBytes: 7,
+ },
+ );
+
+ expect(capture.nodes[0]).toMatchObject({ name: "😀", description: "é" });
+ expect(capture.textCapture).toEqual({
+ status: "truncated",
+ retained_bytes: 6,
+ excluded_fields: 0,
+ truncated_fields: 2,
+ });
+ });
+
+ it("counts accessibility fields omitted without text approval", () => {
+ const capture = captureAccessibility(
+ [
+ {
+ nodes: [
+ {
+ nodeId: "node-1",
+ name: { value: "private name" },
+ description: { value: "private description" },
+ },
+ ],
+ },
+ ],
+ 10,
+ {
+ includeText: false,
+ maximumFieldBytes: 1_024,
+ maximumTotalBytes: 64 * 1_024,
+ },
+ );
+
+ expect(capture.nodes[0]).toMatchObject({ name: null, description: null });
+ expect(capture.textCapture).toEqual({
+ status: "not_approved",
+ retained_bytes: 0,
+ excluded_fields: 2,
+ truncated_fields: 0,
+ });
+ });
});
diff --git a/tests/cdpElectronProvider.test.ts b/tests/cdpElectronProvider.test.ts
new file mode 100644
index 000000000..98cac969b
--- /dev/null
+++ b/tests/cdpElectronProvider.test.ts
@@ -0,0 +1,211 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { pathToFileURL } from "node:url";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { CdpElectronProvider } from "../src/browser/CdpElectronProvider.js";
+import {
+ inspectElectronPageInputSchema,
+ listElectronTargetsInputSchema,
+} from "../src/domain/electronObservation.js";
+import {
+ startFakeCdpBrowser,
+ type FakeCdpBrowser,
+} from "./fixtures/fakeCdpBrowser.js";
+
+describe("CdpElectronProvider", () => {
+ const browsers: FakeCdpBrowser[] = [];
+ const temporary: string[] = [];
+
+ afterEach(async () => {
+ await Promise.all(
+ browsers.splice(0).map(async (browser) => browser.close()),
+ );
+ await Promise.all(
+ temporary
+ .splice(0)
+ .map(async (path) => rm(path, { recursive: true, force: true })),
+ );
+ });
+
+ it("lists and inspects only canonical file targets beneath approved roots", async () => {
+ const root = await electronFixture();
+ const index = join(root, "index.html");
+ const browser = await startFakeCdpBrowser({
+ electronFileUrl: pathToFileURL(index).href,
+ duplicateElectronInventory: true,
+ });
+ browsers.push(browser);
+ const provider = new CdpElectronProvider();
+ const listed = await provider.listTargets(
+ listElectronTargetsInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_file_roots: [root],
+ approved: true,
+ }),
+ );
+ if (!listed.ok) throw listed.error;
+ expect(listed.value.targets.items).toEqual([
+ expect.objectContaining({
+ target_id: "electron-page",
+ file_path: index,
+ }),
+ ]);
+ expect(listed.value.excluded).toEqual({
+ outside_root: 0,
+ unsupported_url: 3,
+ non_page: 1,
+ });
+
+ const inspected = await provider.inspectPage(
+ inspectElectronPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_file_roots: [root],
+ target_id: "electron-page",
+ approved: true,
+ observation_ms: 0,
+ }),
+ );
+ if (!inspected.ok) throw inspected.error;
+ expect(inspected.value.target.file_path).toBe(index);
+ expect(inspected.value.frames).toEqual([
+ expect.objectContaining({ file_path: index }),
+ ]);
+ expect(inspected.value.dom).toMatchObject({ total_nodes: 2 });
+ expect(inspected.value.scripts).toMatchObject({
+ total: 1,
+ items: [
+ expect.objectContaining({
+ file_path: join(root, "app.js"),
+ source: {
+ included: false,
+ reason: "source capture was not approved",
+ },
+ }),
+ ],
+ });
+ expect(inspected.value.resources).toEqual([
+ expect.objectContaining({ file_path: join(root, "app.js") }),
+ ]);
+ const methods = browser.commands.map(({ method }) => method);
+ expect(methods).not.toContain("Runtime.evaluate");
+ expect(methods).not.toContain("Network.enable");
+ expect(methods).not.toContain("Debugger.getScriptSource");
+ expect(methods).toContain("Target.detachFromTarget");
+
+ const missing = await provider.inspectPage(
+ inspectElectronPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_file_roots: [root],
+ target_id: "missing",
+ approved: true,
+ observation_ms: 0,
+ }),
+ );
+ expect(missing).toMatchObject({
+ ok: false,
+ error: {
+ _tag: "BrowserObservationError",
+ operation: "inspect_electron_page",
+ reason: "target_not_found",
+ },
+ });
+ });
+
+ it("captures Electron script source only after separate approval", async () => {
+ const root = await electronFixture();
+ const browser = await startFakeCdpBrowser({
+ electronFileUrl: pathToFileURL(join(root, "index.html")).href,
+ });
+ browsers.push(browser);
+ const result = await new CdpElectronProvider().inspectPage(
+ inspectElectronPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_file_roots: [root],
+ target_id: "electron-page",
+ approved: true,
+ observation_ms: 0,
+ include_script_sources: true,
+ source_capture_approved: true,
+ }),
+ );
+ if (!result.ok) throw result.error;
+ expect(result.value.scripts.items[0]?.source).toMatchObject({
+ included: true,
+ artifact: { text: "export const observed = 'source-secret';" },
+ });
+ expect(browser.commands.map(({ method }) => method)).toContain(
+ "Debugger.getScriptSource",
+ );
+ });
+
+ it("rebases DOM parent indexes across allowed file documents", async () => {
+ const root = await electronFixture();
+ const browser = await startFakeCdpBrowser({
+ electronFileUrl: pathToFileURL(join(root, "index.html")).href,
+ extraCollections: true,
+ });
+ browsers.push(browser);
+ const result = await new CdpElectronProvider().inspectPage(
+ inspectElectronPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_file_roots: [root],
+ target_id: "electron-page",
+ approved: true,
+ observation_ms: 0,
+ }),
+ );
+
+ if (!result.ok) throw result.error;
+ expect(result.value.dom).toMatchObject({
+ total_nodes: 4,
+ nodes: [
+ { index: 0, parent_index: -1 },
+ { index: 1, parent_index: 0 },
+ { index: 2, parent_index: -1 },
+ { index: 3, parent_index: 2 },
+ ],
+ });
+ });
+
+ it("rejects mixed Electron evidence when the main frame navigates", async () => {
+ const root = await electronFixture();
+ const page = join(root, "index.html");
+ const next = join(root, "next.html");
+ await writeFile(next, "next");
+ const browser = await startFakeCdpBrowser({
+ electronFileUrl: pathToFileURL(page).href,
+ navigateDuringCaptureUrl: pathToFileURL(next).href,
+ });
+ browsers.push(browser);
+ const result = await new CdpElectronProvider().inspectPage(
+ inspectElectronPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_file_roots: [root],
+ target_id: "electron-page",
+ approved: true,
+ observation_ms: 0,
+ }),
+ );
+
+ expect(result).toMatchObject({
+ ok: false,
+ error: {
+ _tag: "BrowserObservationError",
+ operation: "inspect_electron_page",
+ reason: "target_changed",
+ },
+ });
+ });
+
+ const electronFixture = async (): Promise => {
+ const root = await mkdtemp(join(tmpdir(), "rea-electron-provider-"));
+ temporary.push(root);
+ await writeFile(join(root, "index.html"), "");
+ await writeFile(join(root, "app.js"), "export const app = true;");
+ await writeFile(join(root, "child.html"), "child
");
+ return root;
+ };
+});
diff --git a/tests/cdpSafeMetadata.test.ts b/tests/cdpSafeMetadata.test.ts
new file mode 100644
index 000000000..882a2ad1d
--- /dev/null
+++ b/tests/cdpSafeMetadata.test.ts
@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+
+import { safeResponseMetadata } from "../src/browser/CdpSafeMetadata.js";
+
+const origin = "https://app.example.test";
+
+describe("safe CDP response metadata", () => {
+ it("retains only allowlisted header structure and redacted approved links", () => {
+ const captured = safeResponseMetadata(
+ "request-1",
+ `${origin}/api`,
+ {
+ mimeType: "application/json",
+ headers: {
+ Authorization: "Bearer credential-secret",
+ Cookie: "session=cookie-secret",
+ "Set-Cookie": "session=response-secret",
+ Link: `; rel="mcp service-desc"; title="a,b", ; rel="mcp"`,
+ "Content-Security-Policy":
+ "default-src 'self'; script-src 'nonce-nonce-secret' 'sha256-hash-secret' https://private.example.test",
+ "Permissions-Policy":
+ "camera=(), geolocation=(self), invalid secret=()",
+ "X-Model-Context": "agent-header-secret",
+ },
+ },
+ new Set([origin]),
+ );
+
+ expect(captured.response).toMatchObject({
+ url: `${origin}/api`,
+ csp: {
+ nonce_count: 1,
+ hash_count: 1,
+ directives: expect.arrayContaining([
+ expect.objectContaining({
+ name: "script-src",
+ sources: expect.arrayContaining([
+ { kind: "external_origin", value: null },
+ ]),
+ }),
+ ]),
+ },
+ links: [
+ {
+ href: `${origin}/agent?token=%5BREDACTED%5D`,
+ destination_scope: "approved",
+ rel: ["mcp", "service-desc"],
+ as: null,
+ type: null,
+ crossorigin: null,
+ },
+ expect.objectContaining({
+ href: null,
+ destination_scope: "outside_policy",
+ }),
+ ],
+ policies: { permissions_policy_features: ["camera", "geolocation"] },
+ });
+ expect(captured.agentHints).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ mechanism: "link_rel" }),
+ expect.objectContaining({
+ mechanism: "response_header",
+ declaration: "x-model-context",
+ }),
+ ]),
+ );
+ const serialized = JSON.stringify(captured);
+ for (const secret of [
+ "credential-secret",
+ "cookie-secret",
+ "response-secret",
+ "link-secret",
+ "nonce-secret",
+ "hash-secret",
+ "agent-header-secret",
+ "private.example.test",
+ ])
+ expect(serialized).not.toContain(secret);
+ });
+
+ it("reports well-known agent resources as untrusted observations", () => {
+ const captured = safeResponseMetadata(
+ "request-2",
+ `${origin}/.well-known/mcp?token=secret`,
+ { headers: {} },
+ new Set([origin]),
+ );
+
+ expect(captured.agentHints).toEqual([
+ {
+ mechanism: "well_known_resource",
+ declaration: "/.well-known/mcp",
+ url: `${origin}/.well-known/mcp?token=%5BREDACTED%5D`,
+ trust: "page-declared-untrusted",
+ },
+ ]);
+ });
+});
diff --git a/tests/config.test.ts b/tests/config.test.ts
index 575ef99c2..3d88afabd 100644
--- a/tests/config.test.ts
+++ b/tests/config.test.ts
@@ -29,9 +29,37 @@ describe("runtime configuration", () => {
expect(result.value.browserObservationEnabled).toBe(false);
expect(result.value.browserCdpEndpoints).toEqual([]);
expect(result.value.browserAllowedOrigins).toEqual([]);
+ expect(result.value.electronObservationEnabled).toBe(false);
+ expect(result.value.electronCdpEndpoints).toEqual([]);
+ expect(result.value.electronFileRoots).toEqual([]);
}
});
+ it("builds a separate Electron endpoint and file-root ceiling", () => {
+ const result = parseConfig({
+ REA_ELECTRON_OBSERVE_ENABLED: "true",
+ REA_ELECTRON_CDP_ENDPOINTS_JSON: '["http://127.0.0.1:9223"]',
+ REA_ELECTRON_FILE_ROOTS_JSON: '["/tmp/electron-app"]',
+ });
+ expect(result.ok).toBe(true);
+ if (!result.ok) return;
+ expect(result.value.permissionCeilings).toContainEqual({
+ capability: "electron_observe",
+ roots: ["/tmp/electron-app"],
+ executables: [],
+ environment_names: [],
+ origins: ["http://127.0.0.1:9223"],
+ network: "loopback",
+ mount: false,
+ });
+ });
+
+ it("rejects relative Electron file roots", () => {
+ expect(
+ parseConfig({ REA_ELECTRON_FILE_ROOTS_JSON: '["relative/app"]' }).ok,
+ ).toBe(false);
+ });
+
it("parses database kind and loader arguments", () => {
expect(
parseConfig({
diff --git a/tests/contractSnapshot.test.ts b/tests/contractSnapshot.test.ts
index 6de2985c0..ff56c53ba 100644
--- a/tests/contractSnapshot.test.ts
+++ b/tests/contractSnapshot.test.ts
@@ -9,6 +9,7 @@ import {
import { NATIVE_TOOL_CONTRACTS } from "../src/contracts/nativeToolContracts.js";
import { ARTIFACT_TOOL_CONTRACTS } from "../src/contracts/artifactToolContracts.js";
import { BROWSER_TOOL_CONTRACTS } from "../src/contracts/browserToolContracts.js";
+import { ELECTRON_TOOL_CONTRACTS } from "../src/contracts/electronToolContracts.js";
import {
enhancedOutputSchemas,
officialOutputSchemas,
@@ -36,8 +37,9 @@ describe("tool contract surface", () => {
...NATIVE_TOOL_CONTRACTS,
...ARTIFACT_TOOL_CONTRACTS,
...BROWSER_TOOL_CONTRACTS,
+ ...ELECTRON_TOOL_CONTRACTS,
];
- expect(contracts).toHaveLength(52);
+ expect(contracts).toHaveLength(60);
for (const contract of contracts) {
const inputSchema = z.toJSONSchema(contract.inputSchema, {
target: "draft-07",
@@ -49,12 +51,8 @@ describe("tool contract surface", () => {
});
expect(inputSchema.type).toBe("object");
expect(outputSchema.type).toBe("object");
- expect(contract.annotations).toMatchObject({
- idempotentHint: true,
- });
- expect(contract.annotations.openWorldHint).toBe(
- contract.kind === "browser-provider",
- );
+ expect(typeof contract.annotations.idempotentHint).toBe("boolean");
+ expect(typeof contract.annotations.openWorldHint).toBe("boolean");
expect(typeof contract.annotations.readOnlyHint).toBe("boolean");
expect(typeof contract.annotations.destructiveHint).toBe("boolean");
expect(contract.examples).toHaveLength(1);
@@ -140,16 +138,17 @@ describe("tool contract surface", () => {
}
});
- it("publishes no unconstrained output-schema holes across all 70 tools", () => {
+ it("publishes no unconstrained output-schema holes across all 78 tools", () => {
const contracts = [
...OFFICIAL_TOOL_CONTRACTS,
...ENHANCED_TOOL_CONTRACTS,
...NATIVE_TOOL_CONTRACTS,
...ARTIFACT_TOOL_CONTRACTS,
...BROWSER_TOOL_CONTRACTS,
+ ...ELECTRON_TOOL_CONTRACTS,
...SESSION_TOOL_CONTRACTS,
];
- expect(contracts).toHaveLength(70);
+ expect(contracts).toHaveLength(78);
for (const contract of contracts) {
const schema = z.toJSONSchema(contract.outputSchema, {
target: "draft-07",
diff --git a/tests/electronCli.test.ts b/tests/electronCli.test.ts
new file mode 100644
index 000000000..cf3411964
--- /dev/null
+++ b/tests/electronCli.test.ts
@@ -0,0 +1,108 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+ startFakeCdpBrowser,
+ type FakeCdpBrowser,
+} from "./fixtures/fakeCdpBrowser.js";
+
+const execute = promisify(execFile);
+const INTEGRATION_TEST_TIMEOUT_MS = 20_000;
+
+describe("Electron CLI parity", () => {
+ const browsers: FakeCdpBrowser[] = [];
+ const temporary: string[] = [];
+
+ afterEach(async () => {
+ await Promise.all(
+ browsers.splice(0).map(async (browser) => browser.close()),
+ );
+ await Promise.all(
+ temporary
+ .splice(0)
+ .map(async (path) => rm(path, { recursive: true, force: true })),
+ );
+ });
+
+ it(
+ "returns the same root-confined Electron Evidence contracts",
+ async () => {
+ const root = await mkdtemp(join(tmpdir(), "rea-electron-cli-"));
+ temporary.push(root);
+ await writeFile(
+ join(root, "index.html"),
+ "",
+ );
+ await writeFile(join(root, "app.js"), "export const app = true;");
+ const browser = await startFakeCdpBrowser({
+ electronFileUrl: pathToFileURL(join(root, "index.html")).href,
+ });
+ browsers.push(browser);
+ const environment = {
+ ...process.env,
+ REA_ELECTRON_OBSERVE_ENABLED: "true",
+ REA_ELECTRON_CDP_ENDPOINTS_JSON: JSON.stringify([browser.endpoint]),
+ REA_ELECTRON_FILE_ROOTS_JSON: JSON.stringify([root]),
+ };
+ const listed = await runCli(
+ ["list-electron-targets", browser.endpoint, "--approved", "--json"],
+ environment,
+ );
+ expect(listed).toMatchObject({
+ operation: "list_electron_targets",
+ normalized_result: {
+ targets: { items: [{ target_id: "electron-page" }] },
+ },
+ });
+ const inspected = await runCli(
+ [
+ "inspect-electron-page",
+ browser.endpoint,
+ "electron-page",
+ "--approved",
+ "--observation-ms",
+ "0",
+ "--json",
+ ],
+ environment,
+ );
+ expect(inspected).toMatchObject({
+ operation: "inspect_electron_page",
+ provider: { id: "rea-cdp-electron" },
+ normalized_result: {
+ target: { file_path: join(root, "index.html") },
+ },
+ });
+ },
+ INTEGRATION_TEST_TIMEOUT_MS,
+ );
+});
+
+const runCli = async (
+ arguments_: readonly string[],
+ environment: NodeJS.ProcessEnv,
+): Promise => {
+ try {
+ const { stdout } = await execute(
+ process.execPath,
+ ["scripts/rea.mjs", ...arguments_],
+ { cwd: process.cwd(), env: environment, maxBuffer: 16 * 1_024 * 1_024 },
+ );
+ return JSON.parse(stdout);
+ } catch (cause: unknown) {
+ if (
+ typeof cause === "object" &&
+ cause !== null &&
+ "stdout" in cause &&
+ typeof cause.stdout === "string"
+ )
+ return JSON.parse(cause.stdout);
+ throw cause;
+ }
+};
diff --git a/tests/electronFileScope.test.ts b/tests/electronFileScope.test.ts
new file mode 100644
index 000000000..a472aa51d
--- /dev/null
+++ b/tests/electronFileScope.test.ts
@@ -0,0 +1,57 @@
+import { mkdtemp, mkdir, rm, symlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { pathToFileURL } from "node:url";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+ authorizedElectronFile,
+ canonicalElectronRoots,
+} from "../src/browser/ElectronFileScope.js";
+
+describe("Electron file scope", () => {
+ const temporary: string[] = [];
+
+ afterEach(async () => {
+ await Promise.all(
+ temporary
+ .splice(0)
+ .map(async (path) => rm(path, { recursive: true, force: true })),
+ );
+ });
+
+ it("accepts canonical files within a root and rejects escape forms", async () => {
+ const base = await mkdtemp(join(tmpdir(), "rea-electron-scope-"));
+ temporary.push(base);
+ const root = join(base, "root");
+ const outside = join(base, "outside");
+ await mkdir(root);
+ await mkdir(outside);
+ const allowed = join(root, "index.html");
+ const denied = join(outside, "secret.html");
+ await writeFile(allowed, "allowed");
+ await writeFile(denied, "denied");
+ await symlink(denied, join(root, "escape.html"));
+ const roots = await canonicalElectronRoots([root]);
+
+ expect(
+ await authorizedElectronFile(pathToFileURL(allowed).href, roots),
+ ).toBe(allowed);
+ expect(
+ await authorizedElectronFile(pathToFileURL(denied).href, roots),
+ ).toBeUndefined();
+ expect(
+ await authorizedElectronFile(
+ pathToFileURL(join(root, "escape.html")).href,
+ roots,
+ ),
+ ).toBeUndefined();
+ expect(
+ await authorizedElectronFile("file://server/share/index.html", roots),
+ ).toBeUndefined();
+ expect(
+ await authorizedElectronFile("file:///tmp/root%2Findex.html", roots),
+ ).toBeUndefined();
+ });
+});
diff --git a/tests/electronMcp.test.ts b/tests/electronMcp.test.ts
new file mode 100644
index 000000000..d75ccf7d8
--- /dev/null
+++ b/tests/electronMcp.test.ts
@@ -0,0 +1,131 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { pathToFileURL } from "node:url";
+
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { BinarySession } from "../src/application/BinarySession.js";
+import { loadConfiguredPermissionAuthority } from "../src/application/PermissionConfiguration.js";
+import { CdpElectronProvider } from "../src/browser/CdpElectronProvider.js";
+import { parseConfig } from "../src/config.js";
+import { createServer } from "../src/server/createServer.js";
+import { observed } from "./fixtures/analysisExecution.js";
+import {
+ startFakeCdpBrowser,
+ type FakeCdpBrowser,
+} from "./fixtures/fakeCdpBrowser.js";
+
+describe("Electron MCP tools", () => {
+ const browsers: FakeCdpBrowser[] = [];
+ const resources: Array<{ close(): Promise }> = [];
+ const temporary: string[] = [];
+
+ afterEach(async () => {
+ await Promise.all(resources.splice(0).map(async (item) => item.close()));
+ await Promise.all(
+ browsers.splice(0).map(async (browser) => browser.close()),
+ );
+ await Promise.all(
+ temporary
+ .splice(0)
+ .map(async (path) => rm(path, { recursive: true, force: true })),
+ );
+ });
+
+ it("exposes root-confined Electron discovery and inspection as Evidence v2", async () => {
+ const root = await mkdtemp(join(tmpdir(), "rea-electron-mcp-"));
+ temporary.push(root);
+ await writeFile(join(root, "index.html"), "");
+ await writeFile(join(root, "app.js"), "export const app = true;");
+ const browser = await startFakeCdpBrowser({
+ electronFileUrl: pathToFileURL(join(root, "index.html")).href,
+ });
+ browsers.push(browser);
+ const config = parseConfig({
+ REA_ELECTRON_OBSERVE_ENABLED: "true",
+ REA_ELECTRON_CDP_ENDPOINTS_JSON: JSON.stringify([browser.endpoint]),
+ REA_ELECTRON_FILE_ROOTS_JSON: JSON.stringify([root]),
+ });
+ if (!config.ok) throw config.error;
+ const authority = await loadConfiguredPermissionAuthority(config.value);
+ if (!authority.ok) throw authority.error;
+ const session = new BinarySession(() => ({
+ execute: () => Promise.resolve(observed(null)),
+ close: () => Promise.resolve(),
+ }));
+ const server = createServer(session, session, {
+ electronObservation: new CdpElectronProvider(),
+ permissionAuthority: authority.value,
+ availabilityPolicy: () => ({
+ processCaptureEnabled: false,
+ evidenceFileRoots: 0,
+ electronObservationEnabled: true,
+ }),
+ });
+ const client = new Client({ name: "electron-mcp-test", version: "1" });
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ resources.push(client, server, session);
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+
+ const listed = await client.callTool({
+ name: "list_electron_targets",
+ arguments: {
+ cdp_endpoint: browser.endpoint,
+ allowed_file_roots: [root],
+ approved: true,
+ },
+ });
+ expect(listed.isError).not.toBe(true);
+ expect(listed.structuredContent).toMatchObject({
+ operation: "list_electron_targets",
+ provider: { id: "rea-cdp-electron" },
+ normalized_result: {
+ targets: { items: [{ target_id: "electron-page" }] },
+ },
+ });
+ const inspected = await client.callTool({
+ name: "inspect_electron_page",
+ arguments: {
+ cdp_endpoint: browser.endpoint,
+ allowed_file_roots: [root],
+ target_id: "electron-page",
+ approved: true,
+ observation_ms: 0,
+ },
+ });
+ expect(inspected.isError).not.toBe(true);
+ expect(inspected.structuredContent).toMatchObject({
+ operation: "inspect_electron_page",
+ normalized_result: {
+ target: { file_path: join(root, "index.html") },
+ scripts: {
+ items: [expect.objectContaining({ file_path: join(root, "app.js") })],
+ },
+ },
+ });
+ const outside = join(root, "..", `outside-${Date.now().toString(16)}`);
+ await mkdir(outside);
+ temporary.push(outside);
+ const commandsBeforeDenial = browser.commands.length;
+ const denied = await client.callTool({
+ name: "list_electron_targets",
+ arguments: {
+ cdp_endpoint: browser.endpoint,
+ allowed_file_roots: [outside],
+ approved: true,
+ },
+ });
+ expect(denied.isError).toBe(true);
+ expect(denied.structuredContent).toMatchObject({
+ error: {
+ code: "permission_required",
+ details: { missing: { roots: [outside] } },
+ },
+ });
+ expect(browser.commands).toHaveLength(commandsBeforeDenial);
+ });
+});
diff --git a/tests/enhancedTools.test.ts b/tests/enhancedTools.test.ts
index ca4883fe9..4b1a3b01f 100644
--- a/tests/enhancedTools.test.ts
+++ b/tests/enhancedTools.test.ts
@@ -4,7 +4,11 @@ import { afterEach, describe, expect, it } from "vitest";
import type { AnalysisOperationPort } from "../src/application/AnalysisProvider.js";
import { EnhancedTools } from "../src/application/EnhancedTools.js";
-import { ENHANCED_TOOL_CONTRACTS } from "../src/contracts/toolContracts.js";
+import {
+ ENHANCED_TOOL_CONTRACTS,
+ SESSION_TOOL_CONTRACTS,
+ TOOL_CONTRACTS,
+} from "../src/contracts/toolContracts.js";
import { AnalysisOutputError } from "../src/domain/errors.js";
import { jsonValueSchema, type JsonValue } from "../src/domain/jsonValue.js";
import { err } from "../src/domain/result.js";
@@ -180,10 +184,12 @@ const jsonResult = (result: CallToolResult): JsonValue => {
};
describe("enhanced MCP tools", () => {
- it("lists the complete 33 plus 10 surface", async () => {
+ it("lists the complete target-open analysis surface", async () => {
const client = await connect();
const listed = await client.listTools();
- expect(listed.tools).toHaveLength(52);
+ expect(listed.tools).toHaveLength(
+ TOOL_CONTRACTS.length - SESSION_TOOL_CONTRACTS.length,
+ );
expect(
listed.tools
.map(({ name }) => name)
diff --git a/tests/fixtures/fakeCdpBrowser.ts b/tests/fixtures/fakeCdpBrowser.ts
index 724bf5a3e..1fb384aae 100644
--- a/tests/fixtures/fakeCdpBrowser.ts
+++ b/tests/fixtures/fakeCdpBrowser.ts
@@ -14,6 +14,12 @@ export interface FakeCdpBrowser {
readonly browserWebSocketUrl: string;
readonly allowedOrigin: string;
readonly commands: readonly FakeCdpCommand[];
+ readonly httpRequests: readonly {
+ readonly url: string;
+ readonly authorization: string | undefined;
+ readonly cookie: string | undefined;
+ readonly referer: string | undefined;
+ }[];
close(): Promise;
}
@@ -29,13 +35,24 @@ interface FakeOptions {
readonly unsupportedMethods?: readonly string[];
readonly transitionalFrameReads?: number;
readonly attachedFrameUrl?: string;
+ readonly frameUrlAfterFirstRead?: string;
readonly navigateDuringObservationUrl?: string;
readonly navigateDuringCaptureUrl?: string;
+ readonly navigateDuringScreenshotUrl?: string;
readonly extraCollections?: boolean;
readonly foreignSessionEvents?: boolean;
readonly redirectToDisallowedOrigin?: boolean;
readonly unrelatedWorker?: boolean;
readonly binaryWebSocketEvent?: boolean;
+ readonly invalidBinaryWebSocketEvent?: boolean;
+ readonly sourceMapBody?: string;
+ readonly sessionTimeline?: "same_origin" | "outside_policy";
+ readonly sensitiveShapes?: boolean;
+ readonly invalidResponseBodyBase64?: boolean;
+ readonly webMcpTools?: boolean;
+ readonly webMcpChildLeavesScope?: boolean;
+ readonly electronFileUrl?: string;
+ readonly duplicateElectronInventory?: boolean;
}
/** Start a real HTTP/WebSocket fake at the same seams as a user-owned browser. */
@@ -43,11 +60,30 @@ export const startFakeCdpBrowser = async (
options: FakeOptions = {},
): Promise => {
const commands: FakeCdpCommand[] = [];
+ const httpRequests: {
+ url: string;
+ authorization: string | undefined;
+ cookie: string | undefined;
+ referer: string | undefined;
+ }[] = [];
const sockets = new Set();
let frameTreeReads = 0;
let port = 0;
const http = createServer((request, response) => {
+ httpRequests.push({
+ url: request.url ?? "",
+ authorization: request.headers.authorization,
+ cookie: request.headers.cookie,
+ referer: request.headers.referer,
+ });
response.setHeader("content-type", "application/json");
+ if (
+ request.url?.startsWith("/app.js.map") === true &&
+ options.sourceMapBody !== undefined
+ ) {
+ response.end(options.sourceMapBody);
+ return;
+ }
if (request.url === "/json/version") {
response.end(
options.oversizedDiscovery === true
@@ -138,6 +174,7 @@ export const startFakeCdpBrowser = async (
browserWebSocketUrl: `ws://127.0.0.1:${String(port)}/devtools/browser/fake`,
allowedOrigin: endpoint,
commands,
+ httpRequests,
async close() {
for (const socket of sockets) socket.terminate();
await new Promise((resolve) => webSockets.close(() => resolve()));
@@ -208,6 +245,17 @@ const targets = (
},
]
: []),
+ ...(options.electronFileUrl === undefined
+ ? []
+ : [
+ {
+ id: "electron-page",
+ type: "page",
+ title: "Electron application",
+ url: options.electronFileUrl,
+ attached: false,
+ },
+ ]),
];
const parseCommand = (text: string): FakeCdpCommand => {
@@ -245,19 +293,44 @@ const resultFor = (
case "Page.getFrameTree":
return frameTree(
port,
- frameTreeReads <= (options.transitionalFrameReads ?? 0)
- ? ":"
- : options.attachedFrameUrl,
+ frameTreeReads > 1 && options.frameUrlAfterFirstRead !== undefined
+ ? options.frameUrlAfterFirstRead
+ : frameTreeReads <= (options.transitionalFrameReads ?? 0)
+ ? ":"
+ : (options.electronFileUrl ?? options.attachedFrameUrl),
options.extraCollections === true,
);
case "Page.getResourceTree":
- return resourceTree(port, options.extraCollections === true);
+ return resourceTree(
+ port,
+ options.extraCollections === true,
+ options.electronFileUrl,
+ options.duplicateElectronInventory === true,
+ );
case "DOMSnapshot.captureSnapshot":
- return domSnapshot(port);
+ return domSnapshot(
+ port,
+ options.electronFileUrl,
+ options.extraCollections === true,
+ );
case "Accessibility.getFullAXTree":
return accessibilityTree(options.extraCollections === true);
case "Debugger.getScriptSource":
return { scriptSource: "export const observed = 'source-secret';" };
+ case "Network.getResponseBody":
+ return options.invalidResponseBodyBase64 === true
+ ? { body: "%%%not-base64%%%", base64Encoded: true }
+ : {
+ body: JSON.stringify({
+ result: { ok: true, token: "response-body-secret" },
+ items: [{ id: 1 }, { id: 2 }],
+ }),
+ base64Encoded: false,
+ };
+ case "Page.captureScreenshot":
+ return {
+ data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PzWvWQAAAABJRU5ErkJggg==",
+ };
case "Target.getTargets":
return { targetInfos: targets(port, options).map(endpointTargetToInfo) };
case "Storage.getUsageAndQuota":
@@ -348,20 +421,38 @@ const frameTree = (
const resourceTree = (
port: number,
extraCollections = false,
+ electronFileUrl?: string,
+ duplicateElectronInventory = false,
): Readonly> => ({
frameTree: {
frame: {
id: "frame-main",
loaderId: "loader-main",
- url: `http://127.0.0.1:${String(port)}/app`,
+ url: electronFileUrl ?? `http://127.0.0.1:${String(port)}/app`,
},
resources: [
{
- url: `http://127.0.0.1:${String(port)}/app.js?api_key=resource-secret`,
+ url:
+ electronFileUrl === undefined
+ ? `http://127.0.0.1:${String(port)}/app.js?token=script-secret`
+ : new URL("app.js", electronFileUrl).href,
type: "Script",
mimeType: "text/javascript",
contentSize: 128,
},
+ ...(duplicateElectronInventory
+ ? [
+ {
+ url:
+ electronFileUrl === undefined
+ ? `http://127.0.0.1:${String(port)}/app.js?token=script-secret`
+ : new URL("app.js", electronFileUrl).href,
+ type: "Script",
+ mimeType: "text/javascript",
+ contentSize: 128,
+ },
+ ]
+ : []),
...(extraCollections
? [
{
@@ -381,16 +472,30 @@ const resourceTree = (
},
});
-const domSnapshot = (port: number): Readonly> => {
+const domSnapshot = (
+ port: number,
+ electronFileUrl?: string,
+ extraCollections = false,
+): Readonly> => {
+ const secondDocumentUrl =
+ electronFileUrl !== undefined && extraCollections
+ ? new URL("child.html", electronFileUrl).href
+ : "https://private.example.test/frame";
const strings = [
- `http://127.0.0.1:${String(port)}/app`,
+ electronFileUrl ?? `http://127.0.0.1:${String(port)}/app`,
"#document",
"",
- "HTML",
+ "LINK",
"token",
"dom-secret",
- "https://private.example.test/frame",
+ secondDocumentUrl,
"PRIVATE-TEXT",
+ "href",
+ "/agent?token=dom-url-secret",
+ "rel",
+ "mcp",
+ "DIV",
+ "child text",
];
return {
strings,
@@ -402,18 +507,27 @@ const domSnapshot = (port: number): Readonly> => {
nodeName: [1, 3],
nodeValue: [2, 2],
parentIndex: [-1, 0],
- attributes: [[], [4, 5]],
+ attributes: [[], [4, 5, 8, 9, 10, 11]],
},
},
{
documentURL: 6,
- nodes: {
- nodeType: [3],
- nodeName: [1],
- nodeValue: [7],
- parentIndex: [-1],
- attributes: [[]],
- },
+ nodes:
+ electronFileUrl !== undefined && extraCollections
+ ? {
+ nodeType: [9, 1],
+ nodeName: [1, 12],
+ nodeValue: [2, 13],
+ parentIndex: [-1, 0],
+ attributes: [[], []],
+ }
+ : {
+ nodeType: [3],
+ nodeName: [1],
+ nodeValue: [7],
+ parentIndex: [-1],
+ attributes: [[]],
+ },
},
],
};
@@ -461,13 +575,28 @@ const emitEvents = (
});
event(socket, "Debugger.scriptParsed", command.sessionId, {
scriptId: "script-allowed",
- url: `http://127.0.0.1:${String(port)}/app.js?token=script-secret`,
+ url:
+ options.electronFileUrl === undefined
+ ? `http://127.0.0.1:${String(port)}/app.js?token=script-secret`
+ : new URL("app.js", options.electronFileUrl).href,
hash: "cdp-hash",
length: 40,
isModule: true,
scriptLanguage: "JavaScript",
sourceMapURL: `http://127.0.0.1:${String(port)}/app.js.map?token=map-secret`,
});
+ if (
+ options.electronFileUrl !== undefined &&
+ options.duplicateElectronInventory === true
+ )
+ event(socket, "Debugger.scriptParsed", command.sessionId, {
+ scriptId: "script-allowed-duplicate",
+ url: new URL("app.js", options.electronFileUrl).href,
+ hash: "cdp-hash",
+ length: 40,
+ isModule: true,
+ scriptLanguage: "JavaScript",
+ });
event(socket, "Debugger.scriptParsed", command.sessionId, {
scriptId: "script-private",
url: "https://private.example.test/private.js?secret=forbidden",
@@ -498,14 +627,27 @@ const emitEvents = (
request: {
url,
method: "POST",
- headers: { Authorization: "Bearer request-secret" },
- postData: "request-body-secret",
+ headers: {
+ Authorization: "Bearer request-secret",
+ "Content-Type": "application/json; charset=utf-8",
+ },
+ postData: JSON.stringify({
+ operation: "lookup",
+ token: "request-body-secret",
+ filters: { active: true },
+ }),
},
initiator: {
type: "script",
- callFrames: [
- { url: `${url}#caller-secret`, lineNumber: 3, columnNumber: 5 },
- ],
+ stack: {
+ callFrames: [
+ {
+ url: `http://127.0.0.1:${String(port)}/app.js?caller=caller-secret`,
+ lineNumber: 3,
+ columnNumber: 5,
+ },
+ ],
+ },
},
});
if (options.redirectToDisallowedOrigin === true)
@@ -526,7 +668,18 @@ const emitEvents = (
: url,
status: 200,
mimeType: "application/json",
- headers: { "Set-Cookie": "response-secret" },
+ headers: {
+ "Set-Cookie": "response-secret",
+ "Content-Length": "321",
+ "Content-Encoding": "br",
+ "Content-Security-Policy":
+ "default-src 'self' https:; script-src 'nonce-csp-secret' 'sha256-hash-secret' https://private.example.test https://127.0.0.1",
+ Link: `; rel="mcp service-desc"; type="application/json", ; rel="mcp"`,
+ "Cross-Origin-Opener-Policy": "same-origin",
+ "Cross-Origin-Embedder-Policy": "require-corp",
+ "Permissions-Policy": "camera=(), geolocation=(self)",
+ "X-Model-Context": "header-secret",
+ },
},
});
event(socket, "Network.loadingFinished", command.sessionId, {
@@ -539,19 +692,51 @@ const emitEvents = (
});
event(socket, "Network.webSocketFrameSent", command.sessionId, {
requestId: "websocket-1",
- response: { opcode: 1, payloadData: "websocket-secret" },
+ response: {
+ opcode: 1,
+ payloadData:
+ options.sensitiveShapes === true
+ ? JSON.stringify({
+ event: "updated",
+ token: "websocket-secret",
+ payload: { count: 2 },
+ })
+ : "websocket-secret",
+ },
});
if (options.binaryWebSocketEvent === true)
event(socket, "Network.webSocketFrameReceived", command.sessionId, {
requestId: "websocket-1",
- response: { opcode: 2, payloadData: "AQID" },
+ response: {
+ opcode: 2,
+ payloadData:
+ options.invalidBinaryWebSocketEvent === true ? "%%%" : "AQID",
+ },
});
}
if (command.method === "Runtime.enable") {
event(socket, "Runtime.consoleAPICalled", command.sessionId, {
type: "log",
timestamp: 123,
- args: [{ type: "string", value: "console-secret" }],
+ args: [
+ {
+ type: "string",
+ value:
+ options.sensitiveShapes === true
+ ? "authorization=Bearer console-secret"
+ : "console-secret",
+ },
+ ...(options.sensitiveShapes === true
+ ? [
+ { type: "number", value: 42 },
+ {
+ type: "object",
+ objectId: "must-not-be-expanded",
+ description: "object-secret",
+ },
+ ]
+ : []),
+ ],
stackTrace: {
callFrames: [
{
@@ -568,6 +753,85 @@ const emitEvents = (
args: [{ type: "string", value: "unknown-console-value-secret" }],
});
}
+ if (command.method === "WebMCP.enable" && options.webMcpTools === true) {
+ event(socket, "WebMCP.toolsAdded", command.sessionId, {
+ tools: [
+ {
+ name: "search_orders",
+ description: "Search orders; authorization=Bearer tool-secret",
+ frameId: "frame-main",
+ backendNodeId: 42,
+ inputSchema: {
+ type: "object",
+ properties: {
+ orderId: { type: "string", example: "schema-secret" },
+ includeItems: { type: "boolean", default: true },
+ },
+ required: ["orderId"],
+ },
+ annotations: {
+ readOnly: true,
+ untrustedContent: true,
+ autosubmit: false,
+ },
+ stackTrace: {
+ callFrames: [
+ {
+ url: `http://127.0.0.1:${String(port)}/app.js?token=tool-source-secret`,
+ lineNumber: 12,
+ columnNumber: 4,
+ },
+ ],
+ },
+ },
+ {
+ name: "private_tool",
+ description: "private-tool-secret",
+ frameId: "frame-private",
+ },
+ ...(options.extraCollections === true
+ ? [
+ {
+ name: "update_order",
+ description: "Update an order",
+ frameId: "frame-main",
+ inputSchema: {
+ type: "object",
+ properties: { orderId: { type: "string" } },
+ },
+ },
+ ]
+ : []),
+ ...(options.webMcpChildLeavesScope === true
+ ? [
+ {
+ name: "child_tool",
+ description: "Must be removed after child navigation",
+ frameId: "frame-child",
+ },
+ ]
+ : []),
+ ],
+ });
+ if (options.webMcpChildLeavesScope === true) {
+ event(socket, "Page.frameNavigated", command.sessionId, {
+ frame: {
+ id: "frame-child",
+ parentId: "frame-main",
+ url: "https://private.example.test/escaped",
+ },
+ });
+ event(socket, "WebMCP.toolsAdded", command.sessionId, {
+ tools: [
+ {
+ name: "escaped_child_tool",
+ description: "cross-origin-child-secret",
+ frameId: "frame-child",
+ },
+ ],
+ });
+ }
+ }
if (
command.method === "DOMSnapshot.captureSnapshot" &&
options.navigateDuringCaptureUrl !== undefined
@@ -578,6 +842,68 @@ const emitEvents = (
url: options.navigateDuringCaptureUrl,
},
});
+ if (
+ command.method === "Page.captureScreenshot" &&
+ options.navigateDuringScreenshotUrl !== undefined
+ )
+ event(socket, "Page.frameNavigated", command.sessionId, {
+ frame: {
+ id: "frame-main",
+ url: options.navigateDuringScreenshotUrl,
+ },
+ });
+ if (
+ command.method === "Page.setLifecycleEventsEnabled" &&
+ options.sessionTimeline !== undefined
+ ) {
+ const allowed = `http://127.0.0.1:${String(port)}/reloaded?token=session-secret`;
+ event(socket, "Page.frameRequestedNavigation", command.sessionId, {
+ frameId: "frame-main",
+ url: allowed,
+ reason: "reload",
+ timestamp: 10,
+ });
+ event(socket, "Page.frameNavigated", command.sessionId, {
+ frame: {
+ id: "frame-main",
+ loaderId: "loader-reload",
+ url: allowed,
+ transitionType: "reload",
+ },
+ timestamp: 11,
+ });
+ event(socket, "Page.navigatedWithinDocument", command.sessionId, {
+ frameId: "frame-main",
+ url: `${allowed}#spa-secret`,
+ navigationType: "historyApi",
+ timestamp: 12,
+ });
+ const redirectUrl =
+ options.sessionTimeline === "outside_policy"
+ ? "https://private.example.test/outside?token=redirect-secret"
+ : `http://127.0.0.1:${String(port)}/redirected?token=redirect-secret`;
+ event(socket, "Network.requestWillBeSent", command.sessionId, {
+ requestId: "document-request",
+ frameId: "frame-main",
+ loaderId: "loader-redirect",
+ request: { url: redirectUrl, method: "GET" },
+ redirectResponse: { status: 302 },
+ timestamp: 13,
+ });
+ event(socket, "Network.loadingFailed", command.sessionId, {
+ requestId: "failed-request",
+ frameId: "frame-main",
+ loaderId: "loader-reload",
+ errorText: "net::ERR_CONNECTION_REFUSED",
+ timestamp: 14,
+ });
+ event(socket, "Page.lifecycleEvent", command.sessionId, {
+ frameId: "frame-main",
+ loaderId: "loader-reload",
+ name: "networkIdle",
+ timestamp: 15,
+ });
+ }
};
const event = (
diff --git a/tests/integration/serverIntegration.test.ts b/tests/integration/serverIntegration.test.ts
index ebc3b6809..a512aeeb9 100644
--- a/tests/integration/serverIntegration.test.ts
+++ b/tests/integration/serverIntegration.test.ts
@@ -19,6 +19,10 @@ import { processCaptureSchema } from "../../src/domain/processCapture.js";
import { EMPTY_PROCESS_CAPTURE_EXAMPLE } from "../../src/contracts/processCaptureExample.js";
import { jsonValueSchema } from "../../src/domain/jsonValue.js";
import { PROCESS_PROVIDER } from "../../src/server/sessionToolPolicies.js";
+import {
+ SESSION_TOOL_CONTRACTS,
+ TOOL_CONTRACTS,
+} from "../../src/contracts/toolContracts.js";
const resources: Array<{ close(): Promise }> = [];
@@ -127,7 +131,7 @@ describe("full MCP integration with multi-tool sequences", () => {
});
});
- it("preserves the complete 70-tool inventory with a session", async () => {
+ it("preserves the complete 78-tool inventory with a session", async () => {
const session = new BinarySession(
(_path) =>
({
@@ -150,7 +154,7 @@ describe("full MCP integration with multi-tool sequences", () => {
await client.connect(clientTransport);
const listed = await client.listTools();
- expect(listed.tools).toHaveLength(70);
+ expect(listed.tools).toHaveLength(78);
const names = listed.tools.map((t) => t.name);
expect(names).toContain("open_binary");
expect(names).toContain("close_binary");
@@ -374,12 +378,14 @@ describe("full MCP integration with multi-tool sequences", () => {
});
});
- it("preserves the 52-tool inventory without a session", async () => {
+ it("preserves the target-open tool inventory without a session", async () => {
const client = await connect({
execute: () => Promise.resolve(ok(null)),
});
const listed = await client.listTools();
- expect(listed.tools).toHaveLength(52);
+ expect(listed.tools).toHaveLength(
+ TOOL_CONTRACTS.length - SESSION_TOOL_CONTRACTS.length,
+ );
const names = listed.tools.map((t) => t.name);
expect(names).toContain("binary_overview");
expect(names).toContain("batch_decompile");
diff --git a/tests/jsonShape.test.ts b/tests/jsonShape.test.ts
new file mode 100644
index 000000000..91a0e0ccd
--- /dev/null
+++ b/tests/jsonShape.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+
+import { inferJsonShape } from "../src/domain/jsonShape.js";
+
+describe("inferJsonShape", () => {
+ it("retains paths and types without retaining JSON values", () => {
+ const shape = inferJsonShape(
+ JSON.stringify({
+ token: "super-secret",
+ users: [
+ { id: 1, active: true },
+ { id: "second-secret", active: false },
+ ],
+ optional: null,
+ }),
+ { maximumBytes: 4_096, maximumNodes: 100, maximumDepth: 10 },
+ );
+
+ expect(shape).toMatchObject({
+ root_type: "object",
+ truncated: false,
+ properties: expect.arrayContaining([
+ { path: "/token", types: ["string"], observations: 1 },
+ {
+ path: "/users/*/id",
+ types: ["number", "string"],
+ observations: 2,
+ },
+ {
+ path: "/users/*/active",
+ types: ["boolean"],
+ observations: 2,
+ },
+ ]),
+ });
+ expect(JSON.stringify(shape)).not.toContain("super-secret");
+ expect(JSON.stringify(shape)).not.toContain("second-secret");
+ });
+
+ it("rejects malformed and oversized JSON without returning a prefix", () => {
+ const limits = {
+ maximumBytes: 8,
+ maximumNodes: 100,
+ maximumDepth: 10,
+ };
+ expect(inferJsonShape("not-json", limits)).toBeNull();
+ expect(inferJsonShape('{"secret":"value"}', limits)).toBeNull();
+ });
+
+ it("reports node and depth truncation deterministically", () => {
+ expect(
+ inferJsonShape('{"a":{"b":{"c":1}}}', {
+ maximumBytes: 1_024,
+ maximumNodes: 100,
+ maximumDepth: 1,
+ }),
+ ).toMatchObject({ truncated: true, max_depth_observed: 1 });
+ expect(
+ inferJsonShape("[1,2,3,4]", {
+ maximumBytes: 1_024,
+ maximumNodes: 2,
+ maximumDepth: 10,
+ }),
+ ).toMatchObject({ truncated: true, node_count: 2 });
+ });
+});
diff --git a/tests/pngVisualDiff.test.ts b/tests/pngVisualDiff.test.ts
new file mode 100644
index 000000000..7ffc0b1c3
--- /dev/null
+++ b/tests/pngVisualDiff.test.ts
@@ -0,0 +1,95 @@
+import { deflateSync } from "node:zlib";
+
+import { describe, expect, it } from "vitest";
+
+import { comparePngScreenshots } from "../src/browser/PngVisualDiff.js";
+import {
+ compareWebScreenshotsInputSchema,
+ createWebScreenshotArtifact,
+} from "../src/domain/webScreenshot.js";
+
+describe("PNG visual diff", () => {
+ it("reports exact changed-pixel and channel metrics", () => {
+ const before = artifact(1, 1, [0, 0, 0, 255]);
+ const after = artifact(1, 1, [10, 0, 0, 255]);
+ const result = comparePngScreenshots(
+ compareWebScreenshotsInputSchema.parse({ before, after }),
+ );
+
+ expect(result).toMatchObject({
+ status: "different",
+ compared_pixels: 1,
+ changed_pixels: 1,
+ changed_ratio: 1,
+ maximum_channel_delta: 10,
+ mean_absolute_channel_delta: 2.5,
+ });
+ });
+
+ it("applies a channel threshold and reports dimension mismatch", () => {
+ const one = artifact(1, 1, [0, 0, 0, 255]);
+ const near = artifact(1, 1, [2, 0, 0, 255]);
+ expect(
+ comparePngScreenshots(
+ compareWebScreenshotsInputSchema.parse({
+ before: one,
+ after: near,
+ channel_threshold: 2,
+ }),
+ ).status,
+ ).toBe("identical");
+ expect(
+ comparePngScreenshots(
+ compareWebScreenshotsInputSchema.parse({
+ before: one,
+ after: artifact(2, 1, [0, 0, 0, 255, 0, 0, 0, 255]),
+ }),
+ ),
+ ).toMatchObject({ status: "dimension_mismatch", compared_pixels: 0 });
+ });
+
+ it("rejects images above the caller's decoded pixel limit", () => {
+ const image = artifact(2, 1, [0, 0, 0, 255, 0, 0, 0, 255]);
+ expect(() =>
+ comparePngScreenshots(
+ compareWebScreenshotsInputSchema.parse({
+ before: image,
+ after: image,
+ maximum_pixels: 1,
+ }),
+ ),
+ ).toThrow("oversized PNG");
+ });
+});
+
+const artifact = (width: number, height: number, pixels: readonly number[]) =>
+ createWebScreenshotArtifact(png(width, height, pixels));
+
+const png = (
+ width: number,
+ height: number,
+ pixels: readonly number[],
+): Buffer => {
+ const header = Buffer.alloc(13);
+ header.writeUInt32BE(width, 0);
+ header.writeUInt32BE(height, 4);
+ header[8] = 8;
+ header[9] = 6;
+ const rows: number[] = [];
+ for (let row = 0; row < height; row += 1)
+ rows.push(0, ...pixels.slice(row * width * 4, (row + 1) * width * 4));
+ return Buffer.concat([
+ Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+ chunk("IHDR", header),
+ chunk("IDAT", deflateSync(Buffer.from(rows))),
+ chunk("IEND", Buffer.alloc(0)),
+ ]);
+};
+
+const chunk = (type: string, data: Buffer): Buffer => {
+ const result = Buffer.alloc(12 + data.byteLength);
+ result.writeUInt32BE(data.byteLength, 0);
+ result.write(type, 4, 4, "ascii");
+ data.copy(result, 8);
+ return result;
+};
diff --git a/tests/promptMcp.test.ts b/tests/promptMcp.test.ts
index a95fc6c16..b35c1f8b4 100644
--- a/tests/promptMcp.test.ts
+++ b/tests/promptMcp.test.ts
@@ -54,7 +54,7 @@ describe("guided prompts over MCP", () => {
),
);
}
- expect((await client.listTools()).tools).toHaveLength(70);
+ expect((await client.listTools()).tools).toHaveLength(78);
const result = await client.getPrompt({
name: "investigate_feature",
arguments: {
diff --git a/tests/readmeConsistency.test.ts b/tests/readmeConsistency.test.ts
index 27e73e0ab..54c92c8c3 100644
--- a/tests/readmeConsistency.test.ts
+++ b/tests/readmeConsistency.test.ts
@@ -11,6 +11,7 @@ import {
import { NATIVE_TOOL_CONTRACTS } from "../src/contracts/nativeToolContracts.js";
import { ARTIFACT_TOOL_CONTRACTS } from "../src/contracts/artifactToolContracts.js";
import { BROWSER_TOOL_CONTRACTS } from "../src/contracts/browserToolContracts.js";
+import { ELECTRON_TOOL_CONTRACTS } from "../src/contracts/electronToolContracts.js";
const readmes = [
"README.md",
@@ -26,14 +27,15 @@ const expectedToolCounts = [
NATIVE_TOOL_CONTRACTS.length,
ARTIFACT_TOOL_CONTRACTS.length,
BROWSER_TOOL_CONTRACTS.length,
+ ELECTRON_TOOL_CONTRACTS.length,
SESSION_TOOL_CONTRACTS.length,
] as const;
const toolCountsFromReadme = (content: string, path: string): number[] => {
const lines = content.split(/\r?\n/u);
- const headingIndex = lines.findIndex((line) => /^## .*70/u.test(line));
+ const headingIndex = lines.findIndex((line) => /^## .*78/u.test(line));
if (headingIndex === -1)
- throw new Error(`Missing 70-tool heading in ${path}`);
+ throw new Error(`Missing 78-tool heading in ${path}`);
const counts: number[] = [];
for (const line of lines.slice(headingIndex + 1)) {
diff --git a/tests/runtime.test.ts b/tests/runtime.test.ts
index 60a14c8ea..da3bfa55f 100644
--- a/tests/runtime.test.ts
+++ b/tests/runtime.test.ts
@@ -10,7 +10,7 @@ const fixturePath = fileURLToPath(
);
describe("production stdio runtime", () => {
- it("starts the built entrypoint, lists 70 tools, calls one, and shuts down", async () => {
+ it("starts the built entrypoint, lists 78 tools, calls one, and shuts down", async () => {
const transport = new StdioClientTransport({
command: process.execPath,
args: [mainPath],
@@ -32,7 +32,7 @@ describe("production stdio runtime", () => {
try {
await client.connect(transport);
const tools = await client.listTools();
- expect(tools.tools).toHaveLength(70);
+ expect(tools.tools).toHaveLength(78);
const result = await client.callTool({
name: "current_document",
arguments: {},
@@ -78,7 +78,7 @@ describe("production stdio runtime", () => {
try {
await client.connect(transport);
- expect((await client.listTools()).tools).toHaveLength(70);
+ expect((await client.listTools()).tools).toHaveLength(78);
} finally {
await client.close();
await transport.close();
diff --git a/tests/sensitiveTextCapture.test.ts b/tests/sensitiveTextCapture.test.ts
new file mode 100644
index 000000000..6d00acb11
--- /dev/null
+++ b/tests/sensitiveTextCapture.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ boundedSensitiveText,
+ redactSensitiveText,
+} from "../src/browser/SensitiveTextCapture.js";
+
+describe("sensitive console text", () => {
+ it("redacts assignments, bearer credentials, and JWT-shaped values", () => {
+ const jwt = "eyJabcdefghijk.abcdefghijkl.abcdefghijk";
+ expect(
+ redactSensitiveText(
+ `authorization=Bearer abc.def password='hunter2' api_key=key ${jwt}`,
+ ),
+ ).toBe(
+ "authorization=[REDACTED] password=[REDACTED] api_key=[REDACTED] [REDACTED_JWT]",
+ );
+ });
+
+ it("bounds UTF-8 after redaction without splitting a code point", () => {
+ expect(boundedSensitiveText("password=secret 你好", 22)).toEqual({
+ text: "password=[REDACTED] ",
+ bytes: 20,
+ truncated: true,
+ });
+ });
+});
diff --git a/tests/serverIdentity.test.ts b/tests/serverIdentity.test.ts
index 3f60fe480..ce74a9bd9 100644
--- a/tests/serverIdentity.test.ts
+++ b/tests/serverIdentity.test.ts
@@ -24,11 +24,11 @@ describe("server and catalog identity", () => {
});
expect(PRODUCT_IDENTITY.packageVersion).toBe(packageJson.version);
expect(SDK_IDENTITY.server).toBe("2.0.0-beta.4");
- expect(CLI_COMMAND_NAMES).toHaveLength(30);
- expect(new Set(CLI_COMMAND_NAMES).size).toBe(30);
+ expect(CLI_COMMAND_NAMES).toHaveLength(38);
+ expect(new Set(CLI_COMMAND_NAMES).size).toBe(38);
expect(CATALOG_IDENTITY.counts).toEqual({
- cli_commands: 30,
- mcp_tools: 70,
+ cli_commands: 38,
+ mcp_tools: 78,
mcp_prompts: 6,
mcp_resources: 2,
mcp_resource_templates: 7,
@@ -162,7 +162,7 @@ describe("server and catalog identity", () => {
expect(status.structuredContent).toMatchObject({
result: {
server_identity: {
- catalog: { counts: { mcp_tools: 70, cli_commands: 30 } },
+ catalog: { counts: { mcp_tools: 78, cli_commands: 38 } },
alignment: { state: "mcp_server_restart_required" },
},
tool_availability: expect.arrayContaining([
diff --git a/tests/sessionMcp.test.ts b/tests/sessionMcp.test.ts
index 711758e82..6b67ee338 100644
--- a/tests/sessionMcp.test.ts
+++ b/tests/sessionMcp.test.ts
@@ -76,7 +76,7 @@ describe("target-free MCP lifecycle", () => {
expect(text(before)).toBe(
"No app is open. Ask the user which app to investigate, then call open_binary with its local path.",
);
- expect((await mcp.listTools()).tools).toHaveLength(70);
+ expect((await mcp.listTools()).tools).toHaveLength(78);
const deniedCapture = await mcp.callTool({
name: "capture_process_scenario",
arguments: {
diff --git a/tests/setupSkill.test.ts b/tests/setupSkill.test.ts
index 9e7d33747..9e27a8d8a 100644
--- a/tests/setupSkill.test.ts
+++ b/tests/setupSkill.test.ts
@@ -27,7 +27,7 @@ describe("canonical skill transaction", () => {
expect(await readFile(`${destination}.rea.backup`, "utf8")).toBe(
"stale managed skill\n",
);
- expect(await readFile(destination, "utf8")).toContain('version: "13"');
+ expect(await readFile(destination, "utf8")).toContain('version: "14"');
expect(await readFile(destination, "utf8")).toContain(
`tool_count: ${String(TOOL_CONTRACTS.length)}`,
);
diff --git a/tests/toolContracts.test.ts b/tests/toolContracts.test.ts
index fecebb73f..eb7305a8e 100644
--- a/tests/toolContracts.test.ts
+++ b/tests/toolContracts.test.ts
@@ -9,9 +9,10 @@ import {
import { ARTIFACT_TOOL_CONTRACTS } from "../src/contracts/artifactToolContracts.js";
import { NATIVE_TOOL_CONTRACTS } from "../src/contracts/nativeToolContracts.js";
import { BROWSER_TOOL_CONTRACTS } from "../src/contracts/browserToolContracts.js";
+import { ELECTRON_TOOL_CONTRACTS } from "../src/contracts/electronToolContracts.js";
describe("tool contract inventory", () => {
- it("publishes 52 analysis contracts and eighteen session tools", () => {
+ it("publishes 60 analysis contracts and eighteen session tools", () => {
expect(OFFICIAL_TOOL_CONTRACTS).toHaveLength(33);
expect(ENHANCED_TOOL_CONTRACTS).toHaveLength(10);
expect(NATIVE_TOOL_CONTRACTS).toHaveLength(5);
@@ -19,6 +20,16 @@ describe("tool contract inventory", () => {
expect(BROWSER_TOOL_CONTRACTS.map(({ name }) => name)).toEqual([
"list_browser_targets",
"inspect_web_page",
+ "analyze_web_bundle",
+ "observe_web_session",
+ "discover_webmcp_tools",
+ "compare_web_captures",
+ "capture_web_screenshot",
+ "compare_web_screenshots",
+ ]);
+ expect(ELECTRON_TOOL_CONTRACTS.map(({ name }) => name)).toEqual([
+ "list_electron_targets",
+ "inspect_electron_page",
]);
expect(SESSION_TOOL_CONTRACTS.map(({ name }) => name)).toEqual([
"open_binary",
@@ -40,8 +51,8 @@ describe("tool contract inventory", () => {
"update_unknown",
"verify_unknown_resolution",
]);
- expect(TOOL_CONTRACTS).toHaveLength(70);
- expect(new Set(TOOL_CONTRACTS.map(({ name }) => name)).size).toBe(70);
+ expect(TOOL_CONTRACTS).toHaveLength(78);
+ expect(new Set(TOOL_CONTRACTS.map(({ name }) => name)).size).toBe(78);
});
it("retains documented enhanced-tool limits at the input boundary", () => {
diff --git a/tests/webBundleAnalyzer.test.ts b/tests/webBundleAnalyzer.test.ts
new file mode 100644
index 000000000..5f6fc3a74
--- /dev/null
+++ b/tests/webBundleAnalyzer.test.ts
@@ -0,0 +1,267 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ inspectWebPageInputSchema,
+ webPageInspectionSchema,
+} from "../src/domain/browserObservation.js";
+import { analyzeCapturedWebBundle } from "../src/domain/webBundleAnalyzer.js";
+import {
+ analyzeWebBundleInputSchema,
+ webBundleAnalysisSchema,
+} from "../src/domain/webBundleAnalysis.js";
+import { createWebTextArtifact } from "../src/domain/webContentArtifact.js";
+
+const origin = "https://app.example.test";
+
+describe("web bundle analyzer", () => {
+ it("extracts bounded graph, route, endpoint, vendor, and WebMCP evidence", () => {
+ const source = `
+ import { createApp } from "./chunk.js?token=secret";
+ const lazy = import("./lazy.js");
+ const routes = [{ path: "/users/:id?token=secret" }];
+ fetch("/api/users?authorization=secret");
+ document.modelContext.registerTool({
+ name: "lookup-user",
+ description: "Untrusted page declaration",
+ inputSchema: {
+ type: "object",
+ properties: {
+ userId: { type: "string" },
+ verbose: { type: "boolean" }
+ }
+ }
+ });
+ const __webpack_require__ = () => createApp(routes, lazy);
+ `;
+ const result = analyzeCapturedWebBundle(inspection(source), input());
+
+ expect(result.observations.chunks.edges).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ kind: "static_import",
+ specifier: "./chunk.js?token=secret",
+ resolved_url: `${origin}/assets/chunk.js?token=%5BREDACTED%5D`,
+ }),
+ expect.objectContaining({
+ kind: "dynamic_import",
+ specifier: "./lazy.js",
+ }),
+ ]),
+ );
+ expect(result.observations.routes).toEqual([
+ expect.objectContaining({ value: "/users/:id?token=%5BREDACTED%5D" }),
+ ]);
+ expect(result.observations.endpoints).toEqual([
+ expect.objectContaining({
+ value: "/api/users?authorization=%5BREDACTED%5D",
+ }),
+ ]);
+ expect(result.observations.webmcp_declarations).toEqual([
+ expect.objectContaining({
+ name: "lookup-user",
+ trust: "page-declared-untrusted",
+ schema_property_names: ["userId", "verbose"],
+ }),
+ ]);
+ expect(result.inferences).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({ value: "webpack", confidence: "high" }),
+ expect.objectContaining({ value: "Vue" }),
+ ]),
+ );
+ expect(JSON.stringify(result)).not.toContain("authorization=secret");
+ expect(result.completeness.status).toBe("complete_within_limits");
+ });
+
+ it("reports parser gaps and finding truncation instead of claiming completeness", () => {
+ const malformed = inspection("function broken( {");
+ const failed = analyzeCapturedWebBundle(malformed, input());
+ expect(failed.completeness).toMatchObject({
+ status: "partial",
+ parse_failures: 1,
+ });
+ expect(failed.unknowns[0]?.dimension).toBe("javascript_ast");
+
+ const bounded = analyzeCapturedWebBundle(
+ inspection("fetch('/one'); fetch('/two'); fetch('/three');"),
+ input({ analysis_limits: { max_findings: 1 } }),
+ );
+ expect(bounded.observations.endpoints).toHaveLength(1);
+ expect(bounded.completeness).toMatchObject({
+ status: "truncated",
+ dropped_findings: 2,
+ });
+ });
+
+ it("propagates source-map truncation into completeness and unknowns", () => {
+ const analysis = analyzeCapturedWebBundle(
+ inspection("export {};"),
+ input(),
+ {
+ status: "truncated",
+ requested: 2,
+ processed: 1,
+ dropped: 1,
+ dropped_script_keys: [`scr_${"2".repeat(64)}`],
+ items: [
+ {
+ script_key: `scr_${"1".repeat(64)}`,
+ declared_url: "https://app.example.test/app.js.map",
+ status: "truncated",
+ artifact: null,
+ original_sources: [],
+ original_module_edges: [],
+ mappings: [],
+ limitation: "Source-map response exceeded the byte budget.",
+ },
+ ],
+ },
+ );
+
+ expect(analysis.completeness.status).toBe("truncated");
+ expect(analysis.unknowns).toContainEqual({
+ dimension: "source_maps",
+ reason: "Source-map evidence was truncated by approved limits",
+ affected_script_keys: [`scr_${"1".repeat(64)}`, `scr_${"2".repeat(64)}`],
+ });
+ });
+
+ it("rejects inconsistent source-map coverage counts", () => {
+ const result = analyzeCapturedWebBundle(inspection("export {};"), input());
+ expect(
+ webBundleAnalysisSchema.safeParse({
+ ...result,
+ observations: {
+ ...result.observations,
+ source_maps: {
+ ...result.observations.source_maps,
+ requested: 1,
+ },
+ },
+ }).success,
+ ).toBe(false);
+ });
+});
+
+const input = (overrides: Record = {}) =>
+ analyzeWebBundleInputSchema.parse({
+ ...inspectWebPageInputSchema.parse({
+ cdp_endpoint: "http://127.0.0.1:9222",
+ allowed_origins: [origin],
+ target_id: "page-1",
+ approved: true,
+ include_script_sources: true,
+ }),
+ source_capture_approved: true,
+ ...overrides,
+ });
+
+const inspection = (source: string) =>
+ webPageInspectionSchema.parse({
+ schema_version: 2,
+ browser: {
+ product: "Fake Chrome",
+ protocol_version: "1.3",
+ revision: "1",
+ user_agent: "fake",
+ js_version: "1",
+ },
+ target: {
+ target_id: "page-1",
+ type: "page",
+ title: "App",
+ url: `${origin}/app`,
+ origin,
+ attached: false,
+ },
+ capture_window: {
+ started_at: "2026-07-14T00:00:00.000Z",
+ ended_at: "2026-07-14T00:00:01.000Z",
+ observation_ms: 1_000,
+ },
+ completeness: {
+ status: "attach_limited",
+ conditions: ["attach_limited"],
+ policy_filtered_sections: [],
+ attach_limited_sections: ["network_requests"],
+ truncated_sections: [],
+ unavailable_sections: [],
+ excluded: [],
+ dropped_events: {
+ scripts: 0,
+ network_requests: 0,
+ console_events: 0,
+ websocket_connections: 0,
+ websocket_frames: 0,
+ webmcp_tools: 0,
+ timeline_events: 0,
+ total: 0,
+ },
+ },
+ frames: [],
+ dom: { total_nodes: 0, nodes: [] },
+ accessibility: {
+ total_nodes: 0,
+ text_capture: {
+ status: "not_approved",
+ retained_bytes: 0,
+ excluded_fields: 0,
+ truncated_fields: 0,
+ },
+ nodes: [],
+ },
+ scripts: {
+ total: 1,
+ items: [
+ {
+ script_key: `scr_${"1".repeat(64)}`,
+ url: `${origin}/assets/app.js`,
+ origin,
+ cdp_hash: "hash",
+ length: Buffer.byteLength(source),
+ is_module: true,
+ language: "JavaScript",
+ source_map_url: null,
+ resource_reconciliation: {
+ status: "unmatched",
+ reason: "no_exact_sanitized_url",
+ },
+ source: {
+ included: true,
+ artifact: createWebTextArtifact(source, "text/javascript"),
+ },
+ },
+ ],
+ },
+ resources: [],
+ network: {
+ requests: [],
+ websocket_events: [],
+ coverage_started_at: "2026-07-14T00:00:00.000Z",
+ prior_activity_available: false,
+ },
+ console: {
+ events: [],
+ coverage_started_at: "2026-07-14T00:00:00.000Z",
+ prior_activity_available: false,
+ },
+ workers: [],
+ metadata: {
+ responses: [],
+ dom_urls: [],
+ agent_hints: [],
+ excluded_dom_urls: 0,
+ headers_allowlisted: true,
+ },
+ storage: {
+ origin,
+ usage_bytes: null,
+ quota_bytes: null,
+ local_storage_keys: [],
+ session_storage_keys: [],
+ indexed_db_names: [],
+ cache_names: [],
+ values_redacted: true,
+ },
+ limitations: [],
+ });
diff --git a/tests/webCaptureDiff.test.ts b/tests/webCaptureDiff.test.ts
new file mode 100644
index 000000000..65a6df17f
--- /dev/null
+++ b/tests/webCaptureDiff.test.ts
@@ -0,0 +1,151 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import { CdpBrowserProvider } from "../src/browser/CdpBrowserProvider.js";
+import { inspectWebPageInputSchema } from "../src/domain/browserObservation.js";
+import {
+ compareWebCaptures,
+ compareWebCapturesInputSchema,
+} from "../src/domain/webCaptureDiff.js";
+import {
+ startFakeCdpBrowser,
+ type FakeCdpBrowser,
+} from "./fixtures/fakeCdpBrowser.js";
+
+describe("web capture diff", () => {
+ const browsers: FakeCdpBrowser[] = [];
+
+ afterEach(async () => {
+ await Promise.all(
+ browsers.splice(0).map(async (browser) => browser.close()),
+ );
+ });
+
+ it("reports stable observed changes while preserving unknown dimensions", async () => {
+ const browser = await startFakeCdpBrowser();
+ browsers.push(browser);
+ const captured = await new CdpBrowserProvider().inspectPage(
+ inspectWebPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 0,
+ }),
+ );
+ if (!captured.ok) throw captured.error;
+ const after = structuredClone(captured.value);
+ after.scripts.items = [];
+ const request = after.network.requests[0];
+ if (request !== undefined) request.status = 204;
+
+ const result = compareWebCaptures(
+ compareWebCapturesInputSchema.parse({
+ before: { inspection: captured.value },
+ after: { inspection: after },
+ }),
+ );
+
+ expect(result.overall_status).toBe("changed");
+ expect(result.dimensions.scripts).toMatchObject({
+ status: "changed",
+ total_changes: 1,
+ changes: [expect.objectContaining({ change: "removed" })],
+ });
+ expect(result.dimensions.network).toMatchObject({
+ status: "changed",
+ changes: [expect.objectContaining({ change: "modified" })],
+ });
+ expect(result.dimensions.webmcp).toMatchObject({
+ status: "unknown",
+ total_changes: 0,
+ });
+ });
+
+ it("does not claim unchanged when a relevant section is incomplete", async () => {
+ const browser = await startFakeCdpBrowser();
+ browsers.push(browser);
+ const captured = await new CdpBrowserProvider().inspectPage(
+ inspectWebPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 0,
+ }),
+ );
+ if (!captured.ok) throw captured.error;
+ const incomplete = structuredClone(captured.value);
+ incomplete.completeness.truncated_sections.push("dom");
+
+ const result = compareWebCaptures(
+ compareWebCapturesInputSchema.parse({
+ before: { inspection: incomplete },
+ after: { inspection: captured.value },
+ }),
+ );
+
+ expect(result.dimensions.dom_structure.status).toBe("unknown");
+ expect(result.dimensions.dom_structure.reason).toContain("incomplete");
+ });
+
+ it("ignores transient request IDs and capture-approval state", async () => {
+ const browser = await startFakeCdpBrowser();
+ browsers.push(browser);
+ const captured = await new CdpBrowserProvider().inspectPage(
+ inspectWebPageInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ approved: true,
+ observation_ms: 0,
+ }),
+ );
+ if (!captured.ok) throw captured.error;
+ const after = structuredClone(captured.value);
+ const request = after.network.requests[0];
+ if (request !== undefined) request.request_id = "different-cdp-request-id";
+ const response = after.metadata.responses[0];
+ if (response !== undefined)
+ response.request_id = "different-cdp-request-id";
+ const script = after.scripts.items[0];
+ if (script !== undefined && !script.source.included)
+ script.source.reason = "different approval explanation";
+ markSectionsComplete(captured.value, ["scripts", "metadata"]);
+ markSectionsComplete(after, ["scripts", "metadata"]);
+
+ const result = compareWebCaptures(
+ compareWebCapturesInputSchema.parse({
+ before: { inspection: captured.value },
+ after: { inspection: after },
+ }),
+ );
+
+ expect(result.dimensions.scripts.status).toBe("unchanged");
+ expect(result.dimensions.metadata.status).toBe("unchanged");
+ expect(result.dimensions.network.status).toBe("unknown");
+ expect(result.dimensions.network.total_changes).toBe(0);
+ });
+});
+
+const markSectionsComplete = (
+ inspection: {
+ completeness: {
+ policy_filtered_sections: string[];
+ attach_limited_sections: string[];
+ truncated_sections: string[];
+ unavailable_sections: string[];
+ };
+ },
+ sections: readonly string[],
+): void => {
+ const completed = new Set(sections);
+ for (const key of [
+ "policy_filtered_sections",
+ "attach_limited_sections",
+ "truncated_sections",
+ "unavailable_sections",
+ ] as const)
+ inspection.completeness[key] = inspection.completeness[key].filter(
+ (section) => !completed.has(section),
+ );
+};
diff --git a/tests/webInventory.test.ts b/tests/webInventory.test.ts
new file mode 100644
index 000000000..ceec1f55e
--- /dev/null
+++ b/tests/webInventory.test.ts
@@ -0,0 +1,154 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ reconcileCapturedWebScript,
+ reconcileWebScript,
+ stableWebResources,
+ stableWebScriptKey,
+} from "../src/domain/webInventory.js";
+import {
+ createWebTextArtifact,
+ webTextArtifactSchema,
+} from "../src/domain/webContentArtifact.js";
+
+describe("web content artifacts", () => {
+ it("binds UTF-8 content, size, digest, and URI", () => {
+ const artifact = createWebTextArtifact(
+ "const marker = '😀';",
+ "text/javascript",
+ );
+ expect(webTextArtifactSchema.parse(artifact)).toEqual(artifact);
+ expect(artifact.bytes).toBe(Buffer.byteLength(artifact.text));
+ expect(artifact.uri).toBe(`rea://web-content/sha256/${artifact.sha256}`);
+ });
+
+ it("rejects altered content that reuses an artifact digest", () => {
+ const artifact = createWebTextArtifact("original", "text/javascript");
+ expect(
+ webTextArtifactSchema.safeParse({ ...artifact, text: "altered!" })
+ .success,
+ ).toBe(false);
+ });
+});
+
+describe("stable web inventory", () => {
+ const script = {
+ url: "https://app.example.test/assets/app.js",
+ cdp_hash: "stable-cdp-hash",
+ length: 1_024,
+ is_module: true,
+ language: "JavaScript",
+ source_map_url: "https://app.example.test/assets/app.js.map",
+ };
+
+ it("excludes transient CDP and target identity from script keys", () => {
+ expect(stableWebScriptKey(script)).toBe(stableWebScriptKey({ ...script }));
+ expect(stableWebScriptKey({ ...script, length: 1_025 })).not.toBe(
+ stableWebScriptKey(script),
+ );
+ });
+
+ it("sorts resources deterministically and reconciles only exact URLs", () => {
+ const inputs = [
+ {
+ url: "https://app.example.test/assets/vendor.js",
+ origin: "https://app.example.test",
+ type: "Script",
+ mime_type: "text/javascript",
+ content_size: 200,
+ },
+ {
+ url: script.url,
+ origin: "https://app.example.test",
+ type: "Script",
+ mime_type: "text/javascript",
+ content_size: 1_024,
+ },
+ ];
+ const forward = stableWebResources(inputs);
+ const reverse = stableWebResources([...inputs].reverse());
+
+ expect(reverse).toEqual(forward);
+ expect(reconcileWebScript(script, forward)).toEqual({
+ status: "exact",
+ resource_key: forward.find(({ url }) => url === script.url)?.resource_key,
+ });
+ expect(
+ reconcileWebScript({ ...script, url: `${script.url}?v=2` }, forward),
+ ).toEqual({ status: "unmatched", reason: "no_exact_sanitized_url" });
+ });
+
+ it("reports duplicate resource observations as ambiguous", () => {
+ const duplicate = {
+ url: script.url,
+ origin: "https://app.example.test",
+ type: "Script",
+ mime_type: "text/javascript",
+ content_size: 1_024,
+ };
+ const resources = stableWebResources([
+ duplicate,
+ { ...duplicate, content_size: 2_048 },
+ ]);
+
+ expect(reconcileWebScript(script, resources)).toEqual({
+ status: "ambiguous",
+ candidate_resource_keys: resources
+ .map(({ resource_key }) => resource_key)
+ .sort(),
+ });
+ });
+
+ it("deduplicates identical resource observations by stable identity", () => {
+ const duplicate = {
+ url: script.url,
+ origin: "https://app.example.test",
+ type: "Script",
+ mime_type: "text/javascript",
+ content_size: 1_024,
+ };
+
+ expect(stableWebResources([duplicate, duplicate])).toEqual(
+ stableWebResources([duplicate]),
+ );
+ });
+
+ it("reconciles raw URLs independently of stable inventory sort order", () => {
+ const app = {
+ url: script.url,
+ origin: "https://app.example.test",
+ type: "Script",
+ mime_type: "text/javascript",
+ content_size: 1_024,
+ rawUrl: `${script.url}?token=secret`,
+ };
+ const vendor = {
+ url: "https://app.example.test/assets/vendor.js",
+ origin: "https://app.example.test",
+ type: "Script",
+ mime_type: "text/javascript",
+ content_size: 2_048,
+ rawUrl: "https://app.example.test/assets/vendor.js?v=1",
+ };
+
+ for (const rawResources of [
+ [app, vendor],
+ [vendor, app],
+ ]) {
+ const resources = stableWebResources(
+ rawResources.map(({ rawUrl: _rawUrl, ...resource }) => resource),
+ );
+ expect(
+ reconcileCapturedWebScript(
+ { ...script, rawUrl: app.rawUrl },
+ rawResources,
+ resources,
+ ),
+ ).toEqual({
+ status: "exact",
+ resource_key: resources.find(({ url }) => url === script.url)
+ ?.resource_key,
+ });
+ }
+ });
+});
diff --git a/tests/webSourceMapFetcher.test.ts b/tests/webSourceMapFetcher.test.ts
new file mode 100644
index 000000000..0ec347157
--- /dev/null
+++ b/tests/webSourceMapFetcher.test.ts
@@ -0,0 +1,264 @@
+import { describe, expect, it } from "vitest";
+
+import { fetchWebSourceMaps } from "../src/browser/WebSourceMapFetcher.js";
+import { analyzeWebBundleInputSchema } from "../src/domain/webBundleAnalysis.js";
+
+const origin = "https://app.example.test";
+const request = {
+ scriptKey: `scr_${"1".repeat(64)}`,
+ declaredUrl: `${origin}/assets/app.js.map?token=%5BREDACTED%5D`,
+ fetchUrl: `${origin}/assets/app.js.map?token=secret`,
+};
+
+describe("web source-map fetcher", () => {
+ it("fetches without credentials and derives mappings and original modules", async () => {
+ const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
+ const map = JSON.stringify({
+ version: 3,
+ file: "app.js",
+ names: ["entry"],
+ sources: ["../src/main.ts"],
+ sourcesContent: ["import './dependency.ts';\nexport const entry = 1;"],
+ mappings: "AAAAA",
+ });
+ const result = await fetchWebSourceMaps([request], input(), undefined, {
+ fetch: (url, init) => {
+ calls.push({ url: String(url), init });
+ return Promise.resolve(
+ new Response(map, {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ }),
+ );
+ },
+ });
+
+ expect(calls).toHaveLength(1);
+ expect(calls[0]).toMatchObject({
+ url: request.fetchUrl,
+ init: {
+ credentials: "omit",
+ redirect: "manual",
+ referrerPolicy: "no-referrer",
+ },
+ });
+ expect(JSON.stringify(calls[0]?.init)).not.toContain("secret");
+ expect(result).toMatchObject({
+ status: "included",
+ requested: 1,
+ processed: 1,
+ dropped: 0,
+ dropped_script_keys: [],
+ items: [
+ {
+ status: "included",
+ artifact: { media_type: "application/source-map+json" },
+ original_sources: [
+ {
+ source: `${origin}/src/main.ts`,
+ artifact: { media_type: "text/typescript" },
+ },
+ ],
+ original_module_edges: [
+ {
+ kind: "static_import",
+ specifier: "./dependency.ts",
+ resolved_source: `${origin}/src/dependency.ts`,
+ },
+ ],
+ mappings: [
+ {
+ generated_line: 1,
+ generated_column: 0,
+ original_line: 1,
+ original_column: 0,
+ },
+ ],
+ },
+ ],
+ });
+ });
+
+ it("validates sectioned maps and reports bounded mapping truncation", async () => {
+ const regular = {
+ version: 3,
+ names: [],
+ sources: ["a.js"],
+ sourcesContent: ["export const a = 1"],
+ mappings: "AAAA;AACA",
+ };
+ const result = await fetchWebSourceMaps(
+ [request],
+ input({ analysis_limits: { max_source_map_mappings: 1 } }),
+ undefined,
+ {
+ fetch: () =>
+ Promise.resolve(
+ new Response(
+ JSON.stringify({
+ version: 3,
+ sections: [{ offset: { line: 0, column: 0 }, map: regular }],
+ }),
+ { status: 200 },
+ ),
+ ),
+ },
+ );
+
+ expect(result).toMatchObject({
+ status: "truncated",
+ items: [
+ {
+ status: "truncated",
+ mappings: [expect.any(Object)],
+ limitation: expect.stringContaining("truncated from 2 to 1"),
+ },
+ ],
+ });
+ });
+
+ it("reauthorizes every redirect and never contacts a disallowed origin", async () => {
+ const calls: string[] = [];
+ const result = await fetchWebSourceMaps([request], input(), undefined, {
+ fetch: (url) => {
+ calls.push(String(url));
+ return Promise.resolve(
+ new Response(null, {
+ status: 302,
+ headers: { location: "https://private.example.test/map" },
+ }),
+ );
+ },
+ });
+
+ expect(calls).toEqual([request.fetchUrl]);
+ expect(result).toMatchObject({
+ status: "unavailable",
+ items: [{ status: "policy_filtered" }],
+ });
+ });
+
+ it("distinguishes invalid JSON from declared or streamed byte truncation", async () => {
+ for (const response of [
+ new Response("not-json", { status: 200 }),
+ new Response("{}", {
+ status: 200,
+ headers: { "content-length": "999999" },
+ }),
+ ]) {
+ const result = await fetchWebSourceMaps(
+ [request],
+ input({ analysis_limits: { max_source_map_bytes: 100 } }),
+ undefined,
+ { fetch: () => Promise.resolve(response) },
+ );
+ expect(result.items[0]?.status).toBe(
+ response.headers.has("content-length") ? "truncated" : "invalid",
+ );
+ }
+ });
+
+ it("bounds aggregate map count and reports omitted requests", async () => {
+ const calls: string[] = [];
+ const requests = [0, 1, 2].map((index) => ({
+ ...request,
+ scriptKey: `scr_${String(index + 1).repeat(64)}`,
+ fetchUrl: `${origin}/assets/${String(index)}.js.map`,
+ }));
+ const result = await fetchWebSourceMaps(
+ requests,
+ input({ analysis_limits: { max_source_maps: 1 } }),
+ undefined,
+ {
+ fetch: (url) => {
+ calls.push(String(url));
+ return Promise.resolve(validMapResponse());
+ },
+ },
+ );
+
+ expect(calls).toEqual([requests[0]?.fetchUrl]);
+ expect(result).toMatchObject({
+ status: "truncated",
+ requested: 3,
+ processed: 1,
+ dropped: 2,
+ dropped_script_keys: [requests[1]?.scriptKey, requests[2]?.scriptKey],
+ });
+ });
+
+ it("stops after exhausting the aggregate response-byte budget", async () => {
+ const requests = [0, 1, 2].map((index) => ({
+ ...request,
+ scriptKey: `scr_${String(index + 1).repeat(64)}`,
+ fetchUrl: `${origin}/assets/${String(index)}.js.map`,
+ }));
+ const calls: string[] = [];
+ const result = await fetchWebSourceMaps(
+ requests,
+ input({
+ analysis_limits: {
+ max_source_map_bytes: 128,
+ max_total_source_map_bytes: 128,
+ },
+ }),
+ undefined,
+ {
+ fetch: (url) => {
+ calls.push(String(url));
+ return Promise.resolve(validMapResponse());
+ },
+ },
+ );
+
+ expect(calls).toHaveLength(2);
+ expect(result).toMatchObject({
+ status: "truncated",
+ requested: 3,
+ processed: 2,
+ dropped: 1,
+ dropped_script_keys: [requests[2]?.scriptKey],
+ items: [{ status: "included" }, { status: "truncated" }],
+ });
+ });
+
+ it("rejects a per-map byte limit larger than the aggregate limit", () => {
+ const parsed = analyzeWebBundleInputSchema.safeParse({
+ cdp_endpoint: "http://127.0.0.1:9222",
+ allowed_origins: [origin],
+ target_id: "page-1",
+ approved: true,
+ source_capture_approved: true,
+ analysis_limits: {
+ max_source_map_bytes: 2,
+ max_total_source_map_bytes: 1,
+ },
+ });
+
+ expect(parsed.success).toBe(false);
+ });
+});
+
+const validMapResponse = () =>
+ new Response(
+ JSON.stringify({
+ version: 3,
+ names: [],
+ sources: ["a.js"],
+ sourcesContent: ["export const a = 1"],
+ mappings: "AAAA",
+ }),
+ { status: 200 },
+ );
+
+const input = (overrides: Record = {}) =>
+ analyzeWebBundleInputSchema.parse({
+ cdp_endpoint: "http://127.0.0.1:9222",
+ allowed_origins: [origin],
+ target_id: "page-1",
+ approved: true,
+ source_capture_approved: true,
+ fetch_source_maps: true,
+ source_map_fetch_approved: true,
+ ...overrides,
+ });