rea-agents 1.4.0 → 1.6.0

package/README.md

@@ -10,23 +10,27 @@
 
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
-[![68 MCP tools](https://img.shields.io/badge/MCP_tools-68-5c4ee5?style=flat-square)](#68-tools-for-investigation)
+[![78 MCP tools](https://img.shields.io/badge/MCP_tools-78-5c4ee5?style=flat-square)](#78-tools-for-investigation)
 [![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 
-[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [68 tools](#68-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)
 
 <br />
 
 <code>npm install --global rea-agents && rea setup</code>
 
+<br />
+
+<img src="docs/assets/rea-hopper-analysis.png" alt="REA launching its analysis bridge inside Hopper while inspecting a native binary" width="1200" />
+
 </div>
 
 ---
 
 See a feature in an app that you want in your own product? Give the app to your agent—even without its source code. With REA, the agent can investigate the feature, explain how it works, show its evidence, and build a version adapted to your stack and requirements.
 
-REA gives agents one consistent way to investigate software. Today that includes deep native analysis through Hopper, complete function dossiers, reproducible Evidence v2 records, and controlled process capture. The longer-term toolkit extends the same agent workflow to packaged apps, JavaScript bundles, websites, APIs, protocols, mobile artifacts, firmware, runtime behavior, and differences between versions.
+REA gives agents one consistent way to investigate software. Today that includes deep native analysis through Hopper, complete function dossiers, reproducible Evidence v2 records, controlled process capture, passive website and Electron observation, and bounded JavaScript/source-map reconstruction. The longer-term toolkit extends the same agent workflow to APIs, protocols, mobile artifacts, firmware, richer runtime behavior, and differences between versions.
 
 Reverse engineering normally makes the operator choose a tool, learn its API, move evidence between programs, and decide what to inspect next. REA gives that work to the agent through commands, skills, structured results, and repeatable investigation workflows.
 
@@ -290,15 +294,17 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its
 - Analyze Swift and Objective-C metadata without manually untangling every mangled symbol.
 - Leave names, comments, and bookmarks in Hopper so human and agent analysis reinforce each other.
 
-## 68 tools for investigation
+## 78 tools for investigation
 
-| Tool family               | Count | Examples                                                                                                                |
-| ------------------------- | ----: | ----------------------------------------------------------------------------------------------------------------------- |
-| Native inspection         |    33 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations                        |
-| Investigation workflows   |    10 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, call graphs, Swift and Objective-C discovery |
-| Native macOS utilities    |     5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing           |
-| Artifact graph            |     2 | deterministic directory, ZIP/APK/IPA, and ASAR inventory; explicitly selected extraction into an absent owned tree      |
-| Workspace and observation |    18 | target lifecycle, Evidence v2 bundles, process/artifact/function comparison, evidence-linked residual-unknown lifecycle |
+| Tool family               | Count | Examples                                                                                                                         |
+| ------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------- |
+| Native inspection         |    33 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations                                 |
+| Investigation workflows   |    10 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, call graphs, Swift and Objective-C discovery          |
+| Native macOS utilities    |     5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing                    |
+| Artifact graph            |     2 | deterministic directory, ZIP/APK/IPA, and ASAR inventory; explicitly selected extraction into an absent owned tree               |
+| Browser observation       |     8 | exact-origin CDP capture, bundle and source-map analysis, WebMCP discovery, session timelines, capture diff, and visual evidence |
+| Electron observation      |     2 | canonical-root-confined file-page discovery and passive DOM, resource, and optionally approved script-source inspection          |
+| Workspace and observation |    18 | target lifecycle, Evidence v2 bundles, process/artifact/function comparison, evidence-linked residual-unknown lifecycle          |
 
 The public interface describes what the agent is trying to learn. Providers decide how to answer. macOS utilities handle common semantic inspection without launching Hopper; Hopper handles deeper native analysis; the process harness implements controlled behavioral capture.
 
@@ -307,6 +313,8 @@ The public interface describes what the agent is trying to learn. Providers deci
 REA is already useful for native application investigation on macOS:
 
 - Open Mach-O, ELF, PE, `.app`, ZIP, APK, IPA, ASAR, plist, JavaScript, source-map, and Hopper database targets.
+- Attach to a user-owned Chrome-family browser over a configured loopback CDP endpoint; capture exact-origin web structure, safe metadata, approved value-free payload shapes, bundle/source-map evidence, WebMCP declarations, user-action timelines, capture diffs, and explicitly approved screenshots without navigation or JavaScript evaluation.
+- Inspect Electron `file://` renderer pages through a separate canonical-root permission boundary without invoking Electron APIs; script contents remain separately approved and byte bounded.
 - Traverse content-addressed artifact graphs without extraction; on macOS, read-only DMG traversal additionally requires `native_mount_approved: true` and `REA_ARTIFACT_NATIVE_MOUNT_ENABLED=true`. Materialize only approved occurrences into absent output roots.
 - Build bounded function dossiers with pseudocode, assembly, CFG edges, comments, calls, references, strings, and names.
 - Search and trace features across symbols, strings, metadata, references, and call paths.
@@ -327,12 +335,27 @@ REA is already useful for native application investigation on macOS:
 
 Hopper is the first provider, not the boundary of the project. Some current workflows still require Hopper and macOS; every evidence record identifies the provider and limitations behind its result.
 
+### Website observation with CDP
+
+REA can inspect an already-running Chrome-family browser that you own. Browser observation is disabled by default and requires a literal loopback CDP endpoint plus exact approved page origins:
+
+```bash
+export REA_BROWSER_OBSERVE_ENABLED=true
+export REA_BROWSER_CDP_ENDPOINTS_JSON='["http://127.0.0.1:9222"]'
+export REA_BROWSER_ALLOWED_ORIGINS_JSON='["http://127.0.0.1:3000"]'
+
+rea list-browser-targets http://127.0.0.1:9222 --approved --json
+rea inspect-web-page http://127.0.0.1:9222 TARGET_ID --approved --json
+```
+
+All eight browser tools expose the same Evidence v2 contracts over CLI and MCP. Inspection is passive: REA does not evaluate page JavaScript, navigate, click, close the page, or close the browser. Query values, credentials, cookies, authorization headers, storage values, and raw JSON or WebSocket values are never retained. Separately approved captures can retain bounded redacted console primitives, value-free JSON/WebSocket shapes, script sources, accessibility text, or screenshot pixels. Existing activity before attach is explicitly unavailable. See [Website observation with CDP](docs/browser-observation.md) for browser startup, schemas, limits, and the threat model.
+
 ## Roadmap
 
 REA is growing into a toolkit for understanding software across static artifacts and observed behavior. The next capability families are:
 
 1. **Artifact decomposition** — DMG, ASAR, ZIP, packages, universal-binary slices, application resources, embedded frameworks, mobile packages, and artifact graphs.
-2. **Web and Electron investigation** — Playwright/CDP capture of DOM, accessibility trees, screenshots, storage, console, IPC, HTTP, WebSocket, routes, and visual or structural differences.
+2. **Web and Electron investigation** — extend the shipped passive CDP, bundle, visual-diff, and file-page observation with approved interaction, controlled replay, Electron IPC observation, semantic UI differences, and deeper JavaScript reconstruction.
 3. **Deterministic behavior harnesses** — stronger process-tree ownership, protocol fixtures, network policy, filesystem tracing, signals, reconnects, and cross-version comparison.
 4. **JavaScript and source recovery** — bundle indexing, AST/module reconstruction, source-map discovery, historical-source matching, and CodeDB-backed cross-references.
 5. **Runtime observation** — approval-gated LLDB, Frida, system logs, process and filesystem observers, and native API tracing.
@@ -377,8 +400,9 @@ flowchart LR
     Router --> Hopper["Hopper provider"]
     Router --> Native["Native macOS provider"]
     Router --> Artifact["Artifact graph provider"]
+    Router --> Browser["Browser CDP provider"]
     Router --> Process["Process capture provider"]
-    Router -. roadmap .-> More["Browser, dynamic,<br/>and additional static providers"]
+    Router -. roadmap .-> More["Dynamic and additional<br/>static providers"]
     Hopper --> Target["Target software"]
     Process --> Target
     Native --> Target

package/dist/application/AnalysisSnapshotCache.js

@@ -52,12 +52,12 @@ export class AnalysisSnapshotCache {
                 this.#target.format !== snapshot.target.format ||
                 this.#target.architecture !== snapshot.target.architecture))
             this.#entries.clear();
-        this.#target = snapshot.target;
+        this.#target = structuredClone(snapshot.target);
         let imported = 0;
         for (const entry of snapshot.entries) {
             if (!this.#entries.has(entry.query_id))
                 imported += 1;
-            this.#entries.set(entry.query_id, entry);
+            this.#entries.set(entry.query_id, structuredClone(entry));
         }
         return imported;
     }
@@ -69,7 +69,7 @@ export class AnalysisSnapshotCache {
             snapshot_version: 1,
             target: snapshotTarget(target),
             entries: this.entries(),
-            evidence_bundle: evidenceBundle,
+            evidence_bundle: structuredClone(evidenceBundle),
         });
     }
     /** Validate target identity, merge evidence atomically, then stage entries. */
@@ -81,7 +81,9 @@ export class AnalysisSnapshotCache {
     }
     /** Return canonical entries for persistence. */
     entries() {
-        return [...this.#entries.values()].sort((left, right) => left.query_id.localeCompare(right.query_id));
+        return [...this.#entries.values()]
+            .sort((left, right) => left.query_id.localeCompare(right.query_id))
+            .map((entry) => structuredClone(entry));
     }
     /** Replay an exact provider-specific query, marking its cached provenance. */
     lookup(target, operation, parameters, provider) {
@@ -90,7 +92,7 @@ export class AnalysisSnapshotCache {
         if (cached === undefined)
             return undefined;
         const subject = cached.execution.subject;
-        return {
+        return structuredClone({
             result: cached.execution.result,
             rawResult: cached.execution.raw_result,
             provider: cached.execution.provider,
@@ -113,7 +115,7 @@ export class AnalysisSnapshotCache {
                         format: subject.format,
                         architecture: subject.architecture,
                     },
-        };
+        });
     }
     /** Record one successful immutable call unless the cache is full. */
     record(target, operation, parameters, execution) {

package/dist/application/ArtifactGraphConstruction.js

@@ -1,6 +1,14 @@
 import { createHash } from "node:crypto";
 import { extname } from "node:path";
 import canonicalize from "canonicalize";
+/** Index the first occurrence for each canonical logical path. */
+export const indexOccurrencesByPath = (occurrences) => {
+    const byPath = new Map();
+    for (const occurrence of occurrences)
+        if (!byPath.has(occurrence.logical_path))
+            byPath.set(occurrence.logical_path, occurrence);
+    return byPath;
+};
 export const createOccurrence = (entry, path, parent) => ({
     occurrence_id: `occ_${digestCanonical({ path, kind: entry.kind })}`,
     artifact_id: null,
@@ -118,13 +126,14 @@ export const rekeyOccurrences = (rootArtifactId, occurrences) => {
 };
 export const createArtifactEdges = (rootArtifactId, occurrences, producer) => {
     const byId = new Map(occurrences.map((item) => [item.occurrence_id, item]));
+    const byPath = indexOccurrencesByPath(occurrences);
     const edges = [];
     for (const occurrence of occurrences) {
         if (occurrence.parent_occurrence_id === null ||
             occurrence.artifact_id === null)
             continue;
-        const mappedSource = occurrence.logical_path.endsWith(".map")
-            ? occurrences.find(({ logical_path: path }) => path === occurrence.logical_path.slice(0, -".map".length))
+        const mappedSource = occurrence.logical_path.toLowerCase().endsWith(".map")
+            ? byPath.get(occurrence.logical_path.slice(0, -".map".length))
             : undefined;
         const parentArtifactId = mappedSource?.artifact_id ??
             byId.get(occurrence.parent_occurrence_id)?.artifact_id ??

package/dist/application/ArtifactInventory.js

@@ -10,7 +10,7 @@ import { MachOSliceArtifactReader } from "../artifacts/MachOSliceArtifactReader.
 import { NativeDmgArtifactReader } from "../artifacts/NativeDmgArtifactReader.js";
 import { streamChunkToBuffer } from "../artifacts/StreamBytes.js";
 import { artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
-import { classifyArtifactPath, classifyArtifactContent, createArtifactEdges, createArtifactNode, createOccurrence, createRootNode, digestCanonical, materializeDirectoryNodes, nearestParent, pageOf, rekeyOccurrences, rootOccurrenceFor, toOutputLimits, } from "./ArtifactGraphConstruction.js";
+import { classifyArtifactPath, classifyArtifactContent, createArtifactEdges, createArtifactNode, createOccurrence, createRootNode, digestCanonical, indexOccurrencesByPath, materializeDirectoryNodes, nearestParent, pageOf, rekeyOccurrences, rootOccurrenceFor, toOutputLimits, } from "./ArtifactGraphConstruction.js";
 const NATIVE_MOUNT_DISABLED = {
     nativeMountApproved: false,
     nativeMountEnabled: false,
@@ -61,8 +61,9 @@ export const scanCanonicalArtifactInventory = async (path, limits, signal, nativ
                 occurrence.parent_occurrence_id = rootOccurrence.occurrence_id;
         occurrences.unshift(rootOccurrence);
         const occurrenceById = new Map(occurrences.map((occurrence) => [occurrence.occurrence_id, occurrence]));
+        const occurrenceByPath = indexOccurrencesByPath(occurrences);
         const integrityContradictions = pendingContradictions.map((contradiction) => {
-            const occurrence = occurrences.find(({ logical_path: path }) => path === contradiction.logicalPath);
+            const occurrence = occurrenceByPath.get(contradiction.logicalPath);
             if (occurrence === undefined)
                 throw new ArtifactReaderFailure("integrity", "Integrity contradiction lost its graph occurrence");
             const parent = occurrence.parent_occurrence_id === null

package/dist/application/AuthorizedArtifactInventory.js

@@ -2,13 +2,14 @@ import { realpath } from "node:fs/promises";
 import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
 import { withinRoot } from "../reference/ReferenceSourceReaderPaths.js";
 import { scanCanonicalArtifactInventory, } from "./ArtifactInventory.js";
+import { canonicalizeConfiguredRoots } from "./ConfiguredRoots.js";
 /** Resolve, authorize, and scan one artifact without a second path resolution. */
 export const scanAuthorizedArtifactInventory = async (inputPath, roots, limits, signal, integrity) => {
     if (roots.length === 0)
         throw new ArtifactReaderFailure("path", "Artifact input roots are disabled");
     const [path, approved] = await Promise.all([
         realpath(inputPath),
-        Promise.all(roots.map(async (root) => realpath(root))),
+        canonicalizeConfiguredRoots(roots),
     ]);
     if (!approved.some((root) => withinRoot(root, path)))
         throw new ArtifactReaderFailure("path", "Artifact path is outside approved input roots");

package/dist/application/BinarySession.js

@@ -7,7 +7,7 @@ import { EvidenceLedger } from "./EvidenceLedger.js";
 import { UnknownRegistryError } from "../domain/errors.js";
 import { enhancedToolNameSchema } from "../contracts/enhancedInputs.js";
 import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
-import { snapshotMatchesTarget } from "../domain/analysisSnapshot.js";
+import { snapshotMatchesTarget, snapshotTarget, } from "../domain/analysisSnapshot.js";
 import { AnalysisSnapshotCache, isSnapshotCacheable, } from "./AnalysisSnapshotCache.js";
 import { UNKNOWN_REGISTRY_PROVIDER, unknownEvidenceLinks, unknownMutationEvidence, } from "./UnknownEvidence.js";
 import { parseInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
@@ -61,7 +61,7 @@ export class BinarySession {
         if (operation !== undefined) {
             const exact = this.#capabilities?.get(operation)?.provider;
             if (exact !== undefined)
-                return exact;
+                return structuredClone(exact);
             if (enhancedToolNameSchema.safeParse(operation).success) {
                 const providers = new Map();
                 for (const descriptor of this.#capabilities?.values() ?? [])
@@ -71,11 +71,11 @@ export class BinarySession {
                 if (providers.size === 1) {
                     const provider = providers.values().next().value;
                     if (provider !== undefined)
-                        return provider;
+                        return structuredClone(provider);
                 }
             }
         }
-        return this.#providerIdentity;
+        return structuredClone(this.#providerIdentity);
     }
     /** Observe runtime provider-health changes that affect discovery metadata. */
     onAvailabilityChanged(listener) {
@@ -130,12 +130,15 @@ export class BinarySession {
     }
     /** Read one session-retained immutable workspace revision. */
     investigationWorkspace(workspaceId, revision) {
-        return this.#investigationWorkspaces.get(`${workspaceId}:${String(revision)}`);
+        const workspace = this.#investigationWorkspaces.get(`${workspaceId}:${String(revision)}`);
+        return workspace === undefined ? undefined : structuredClone(workspace);
     }
     /** List retained workspace revisions in canonical identity order. */
     investigationWorkspaces() {
-        return [...this.#investigationWorkspaces.values()].sort((left, right) => left.workspace_id.localeCompare(right.workspace_id) ||
-            left.revision - right.revision);
+        return [...this.#investigationWorkspaces.values()]
+            .sort((left, right) => left.workspace_id.localeCompare(right.workspace_id) ||
+            left.revision - right.revision)
+            .map((workspace) => structuredClone(workspace));
     }
     /** Create an approved residual unknown and immutable mutation evidence. */
     recordUnknown(input) {
@@ -191,7 +194,8 @@ export class BinarySession {
                 return err(new EvidenceIntegrityError("Analysis snapshot target does not match the requested binary"));
             if (isAborted(options.signal))
                 return err(new AnalysisCancelledError("open_binary"));
-            if (this.#active?.target.path === parsed.value.path) {
+            if (this.#active?.target.path === parsed.value.path &&
+                snapshotMatchesTarget(snapshotTarget(this.#active.target), parsed.value)) {
                 if (options.snapshot !== undefined) {
                     const imported = this.importAnalysisSnapshot(options.snapshot);
                     if (!imported.ok)
@@ -310,7 +314,9 @@ export class BinarySession {
     }
     /** Return the immutable artifact identity captured before Hopper launched. */
     activeTarget() {
-        return this.#active?.target;
+        return this.#active === undefined
+            ? undefined
+            : structuredClone(this.#active.target);
     }
     /**
      * Invoke a Hopper tool against the active target.
@@ -396,8 +402,17 @@ export class BinarySession {
         this.#emitAvailabilityChanged();
     }
     #emitAvailabilityChanged() {
-        for (const listener of this.#availabilityListeners)
-            listener();
+        for (const listener of this.#availabilityListeners) {
+            try {
+                const notification = listener();
+                if (notification !== undefined)
+                    void notification.catch(() => undefined);
+            }
+            catch {
+                // External observers are best-effort notifications. Contain only the
+                // callback failure so state transitions and other listeners continue.
+            }
+        }
     }
     #serialize(operation) {
         const result = this.#transition.then(operation, operation);

package/dist/application/BoundedJsonFiles.js

@@ -2,7 +2,9 @@ import { lstat, readFile, realpath } from "node:fs/promises";
 import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { EvidenceFileError } from "../domain/errors.js";
+import { isJsonWithinLimits } from "../domain/jsonLimits.js";
 import { err, ok } from "../domain/result.js";
+import { canonicalizeConfiguredRoots } from "./ConfiguredRoots.js";
 /** Read bounded JSON data from a regular file beneath an approved root. */
 export const readBoundedJson = async (path, policy) => {
     if (policy.roots.length === 0)
@@ -26,8 +28,9 @@ export const readBoundedJson = async (path, policy) => {
         catch (cause) {
             return err(new EvidenceFileError("read", "invalid-json", { cause }));
         }
-        const limits = validateJsonLimits(decoded, policy);
-        return limits.ok ? ok(decoded) : limits;
+        return isJsonWithinLimits(decoded, policy)
+            ? ok(decoded)
+            : err(new EvidenceFileError("read", "too-large"));
     }
     catch (cause) {
         return err(new EvidenceFileError("read", "io", { cause }));
@@ -69,8 +72,7 @@ export const writeBoundedText = async (encoded, path, overwrite, policy) => {
     }
 };
 const isApproved = async (candidate, roots) => {
-    for (const configuredRoot of roots) {
-        const root = await realpath(resolve(configuredRoot));
+    for (const root of await canonicalizeConfiguredRoots(roots.map((configuredRoot) => resolve(configuredRoot)))) {
         const relation = relative(root, candidate);
         if (relation === "" ||
             (!relation.startsWith("..") && !isAbsolute(relation)))
@@ -78,31 +80,6 @@ const isApproved = async (candidate, roots) => {
     }
     return false;
 };
-const validateJsonLimits = (root, policy) => {
-    const pending = [
-        { value: root, depth: 0 },
-    ];
-    let nodes = 0;
-    while (pending.length > 0) {
-        const current = pending.pop();
-        if (current === undefined)
-            break;
-        nodes += 1;
-        if (nodes > policy.maxNodes || current.depth > policy.maxDepth)
-            return err(new EvidenceFileError("read", "too-large"));
-        if (typeof current.value === "string" &&
-            current.value.length > policy.maxStringLength)
-            return err(new EvidenceFileError("read", "too-large"));
-        if (typeof current.value !== "object" || current.value === null)
-            continue;
-        for (const [key, value] of Object.entries(current.value)) {
-            if (key.length > policy.maxStringLength)
-                return err(new EvidenceFileError("read", "too-large"));
-            pending.push({ value, depth: current.depth + 1 });
-        }
-    }
-    return ok(null);
-};
 const isFileNotFound = (cause) => typeof cause === "object" &&
     cause !== null &&
     "code" in cause &&

package/dist/application/BrowserEvidence.js

@@ -0,0 +1,107 @@
+import { createEvidence, } from "../domain/evidence.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+/** Create Evidence v2 for a policy-scoped external browser observation. */
+export const createBrowserEvidence = (operation, input, result, provider) => createEvidence(undefined, provider, {
+    predicateType: browserPredicate(operation),
+    operation,
+    parameters: browserParameters(input),
+    result: jsonValueSchema.parse(result),
+    confidence: "observed",
+    authority: "external-service",
+    environment: "browser" in result
+        ? {
+            id: `${result.browser.product}@${result.browser.revision}`,
+            platform: process.platform,
+            architecture: process.arch,
+            isolation: "none",
+        }
+        : null,
+    limitations: result.limitations,
+});
+const browserParameters = (input) => {
+    if (!("cdp_endpoint" in input)) {
+        if ("max_changes" in input)
+            return {
+                before_target_id: input.before.inspection.target.target_id,
+                before_capture_ended_at: input.before.inspection.capture_window.ended_at,
+                after_target_id: input.after.inspection.target.target_id,
+                after_capture_ended_at: input.after.inspection.capture_window.ended_at,
+                max_changes: input.max_changes,
+            };
+        return {
+            before_artifact_uri: input.before.uri,
+            after_artifact_uri: input.after.uri,
+            channel_threshold: input.channel_threshold,
+            maximum_pixels: input.maximum_pixels,
+        };
+    }
+    const scope = {
+        cdp_endpoint: input.cdp_endpoint,
+        allowed_origins: input.allowed_origins,
+    };
+    if (!("target_id" in input))
+        return { ...scope, offset: input.offset, limit: input.limit };
+    if ("screenshot_approved" in input)
+        return {
+            ...scope,
+            target_id: input.target_id,
+            maximum_image_bytes: input.maximum_image_bytes,
+        };
+    if ("max_tools" in input)
+        return {
+            ...scope,
+            target_id: input.target_id,
+            observation_ms: input.observation_ms,
+            max_tools: input.max_tools,
+            max_schema_bytes: input.max_schema_bytes,
+            max_schema_nodes: input.max_schema_nodes,
+            max_schema_depth: input.max_schema_depth,
+        };
+    if (!("include_accessibility_text" in input))
+        return {
+            ...scope,
+            target_id: input.target_id,
+            observation_ms: input.observation_ms,
+            max_timeline_events: input.max_timeline_events,
+        };
+    return {
+        ...scope,
+        target_id: input.target_id,
+        observation_ms: input.observation_ms,
+        include_accessibility_text: input.include_accessibility_text,
+        include_console_text: input.include_console_text,
+        include_json_body_shapes: input.include_json_body_shapes,
+        include_websocket_shapes: input.include_websocket_shapes,
+        include_script_sources: input.include_script_sources,
+        include_storage_keys: input.include_storage_keys,
+        limits: input.limits,
+        ...(input.include_script_sources && "source_capture_approved" in input
+            ? {
+                source_capture_approved: input.source_capture_approved,
+                fetch_source_maps: input.fetch_source_maps,
+                source_map_fetch_approved: input.source_map_fetch_approved,
+                analysis_limits: input.analysis_limits,
+            }
+            : {}),
+    };
+};
+const browserPredicate = (operation) => {
+    switch (operation) {
+        case "list_browser_targets":
+            return "rea.browser-target-list/v1";
+        case "inspect_web_page":
+            return "rea.web-page-inspection/v2";
+        case "analyze_web_bundle":
+            return "rea.web-bundle-analysis/v1";
+        case "observe_web_session":
+            return "rea.web-observation-session/v1";
+        case "discover_webmcp_tools":
+            return "rea.webmcp-discovery/v1";
+        case "compare_web_captures":
+            return "rea.web-capture-diff/v1";
+        case "capture_web_screenshot":
+            return "rea.web-screenshot/v1";
+        case "compare_web_screenshots":
+            return "rea.web-screenshot-diff/v1";
+    }
+};

package/dist/application/BrowserObservationPort.js

@@ -0,0 +1 @@
+export {};

package/dist/application/BrowserObservationService.js

@@ -0,0 +1,116 @@
+import { isLiteralLoopbackHostname, } from "../domain/browserObservation.js";
+import { AnalysisCapabilityUnavailableError, AnalysisProtocolError, PermissionRequiredError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { createBrowserEvidence } from "./BrowserEvidence.js";
+/** Authorize and execute one policy-scoped target discovery observation. */
+export const listBrowserTargets = async (browser, authority, input, options = {}) => {
+    const ready = await prepare(browser, authority, input, "list_browser_targets");
+    if (!ready.ok)
+        return ready;
+    const result = await ready.value.listTargets(input, options);
+    return result.ok
+        ? ok(createBrowserEvidence("list_browser_targets", input, result.value, ready.value.identity()))
+        : result;
+};
+/** Authorize and execute one policy-scoped passive page inspection. */
+export const inspectWebPage = async (browser, authority, input, options = {}) => {
+    const ready = await prepare(browser, authority, input, "inspect_web_page");
+    if (!ready.ok)
+        return ready;
+    const result = await ready.value.inspectPage(input, options);
+    return result.ok
+        ? ok(createBrowserEvidence("inspect_web_page", input, result.value, ready.value.identity()))
+        : result;
+};
+/** Capture approved sources and derive bounded static web-bundle evidence. */
+export const analyzeWebBundle = async (browser, authority, input, options = {}) => {
+    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, authority, input, options = {}) => {
+    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, authority, input, options = {}) => {
+    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, input) => {
+    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, authority, input, options = {}) => {
+    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, input) => {
+    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, authority, input, operation) => {
+    if (authority === undefined)
+        return err(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser observation permission policy is not configured"));
+    const authorized = await authority.authorize({
+        capability: "browser_observe",
+        roots: [],
+        executables: [],
+        environment_names: [],
+        origins: [input.cdp_endpoint, ...input.allowed_origins],
+        network: browserNetworkScope(input.allowed_origins),
+        mount: false,
+        operation_identity: `${operation}:${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 browser === undefined
+        ? err(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser observation provider is not configured"))
+        : ok(browser);
+};
+const requireBrowser = (browser, operation) => browser === undefined
+    ? err(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser comparison provider is not configured"))
+    : ok(browser);
+const browserNetworkScope = (allowedOrigins) => allowedOrigins.every((origin) => {
+    const hostname = new URL(origin).hostname;
+    return isLiteralLoopbackHostname(hostname);
+})
+    ? "loopback"
+    : "external";

package/dist/application/CapabilityInventory.js

@@ -64,6 +64,20 @@ const availabilityFor = (name, kind, targetOpen, targetKind, descriptors, policy
             reason: "policy_disabled",
             remediation: "Configure or grant an evidence_read root.",
         };
+    if (kind === "browser-provider")
+        return policy.browserObservationEnabled === true
+            ? { reason: "available", remediation: null }
+            : {
+                reason: "policy_disabled",
+                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)