rea-agents 1.4.0 → 1.5.0

package/dist/domain/reconstructionVerification.js

@@ -7,7 +7,7 @@ import { parseEvidence } from "./evidence.js";
 import { parseEvidenceBundle } from "./evidenceBundle.js";
 import { functionComparisonResultSchema } from "./functionComparison.js";
 import { functionDossierSchema } from "./hopperValues.js";
-import { processCaptureComparisonSchema, processCaptureSchema, } from "./processCapture.js";
+import { deriveProcessComparisonStatus, PROCESS_COMPARISON_DIMENSIONS, processCaptureComparisonSchema, processCaptureSchema, } from "./processCapture.js";
 import { reconstructionClaimResultSchema, reconstructionSpecificationSchema, reconstructionVerificationResultSchema, } from "./reconstructionVerificationSchemas.js";
 import { reconstructionClaimUnknowns, reconstructionProbes, reconstructionUnknownHeads, } from "./reconstructionUnknowns.js";
 const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
@@ -219,20 +219,7 @@ const observedStatus = (claim, evidence) => {
     return result.status;
 };
 const validateProcessStatus = (result) => {
-    const dimensions = [
-        result.terminal,
-        result.exit,
-        result.filesystem,
-        result.protocol,
-        result.process,
-    ];
-    const expected = dimensions.includes("truncated")
-        ? "truncated"
-        : dimensions.some((status) => ["added", "removed", "changed"].includes(status))
-            ? "changed"
-            : dimensions.includes("unknown")
-                ? "unknown"
-                : "unchanged";
+    const expected = deriveProcessComparisonStatus(PROCESS_COMPARISON_DIMENSIONS.map((dimension) => result[dimension]));
     if (result.status !== expected)
         throw new TypeError("Process comparison status contradicts its dimensions");
 };

package/dist/domain/reconstructionVerificationSchemas.js

@@ -17,10 +17,12 @@ const behavioralClaimSchema = z.object({
     dimension: z.enum([
         "overall",
         "terminal",
+        "interaction",
         "exit",
         "filesystem",
         "protocol",
         "process",
+        "shim",
     ]),
 });
 const functionClaimSchema = z.object({

package/dist/domain/staticRuntimeCorrelation.js

@@ -18,10 +18,12 @@ const functionDimensionSchema = z.enum([
 ]);
 const runtimeDimensionSchema = z.enum([
     "terminal",
+    "interaction",
     "exit",
     "filesystem",
     "protocol",
     "process",
+    "shim",
 ]);
 const expectedPatternSchema = z.enum([
     "cochanged",

package/dist/domain/symbolAnalysis.js

@@ -14,7 +14,7 @@ export const discoverSwiftClasses = (procedures, pattern) => {
 /** Select and deduplicate Objective-C class labels. */
 export const discoverObjcClasses = (names, pattern) => {
     const classes = uniqueByName(names
-        .filter(({ name }) => ["OBJC_CLASS", "OBJC_$_CLASS"].some((marker) => name.includes(marker)) || name.startsWith("_OBJC_"))
+        .filter(({ name }) => ["OBJC_CLASS", "OBJC_$_CLASS"].some((marker) => name.includes(marker)))
         .filter(({ name }) => pattern.length === 0 || name.includes(pattern)));
     return {
         count: classes.length,

package/dist/generatedPackageMetadata.js

@@ -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: "12",
+    skillVersion: "13",
 };

package/dist/main.js

@@ -9,6 +9,7 @@ import { createLogger } from "./logger.js";
 import { projectAnalysisError } from "./domain/errors.js";
 import { readProjectPermissionStore } from "./application/ProjectPermissionStore.js";
 import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
+import { CdpBrowserProvider } from "./browser/CdpBrowserProvider.js";
 const MCP_CONNECTION_LOST = "REA lost its MCP client connection. Restart REA from your MCP client.";
 const MCP_CONNECTION_START_FAILED = "REA could not start its MCP connection. Restart REA from your MCP client; run `rea doctor` if it fails again.";
 const MCP_SHUTDOWN_FAILED = "REA could not close cleanly. End the REA process before starting it again.";
@@ -50,6 +51,7 @@ export const run = async (dependencies = runtimeDependencies()) => {
         return 1;
     }
     const session = createBinarySession(config.value, logger);
+    const browserObservation = new CdpBrowserProvider();
     if (config.value.hopperTargetPath !== undefined) {
         const opened = await session.open(config.value.hopperTargetPath, {
             targetKind: config.value.hopperTargetKind,
@@ -90,10 +92,14 @@ export const run = async (dependencies = runtimeDependencies()) => {
                 investigationInputRoots: runtimeInvestigationRoots,
                 analysisSnapshotFilePolicy: runtimeSnapshotPolicy,
                 permissionAuthority: permissionAuthority.value,
+                browserObservation,
                 artifactIntegrityContinueEnabled: () => currentConfig.artifactIntegrityContinueEnabled,
                 availabilityPolicy: () => ({
                     processCaptureEnabled: currentConfig.processExecutionPolicy.enabled,
                     evidenceFileRoots: currentConfig.evidenceFilePolicy.roots.length,
+                    browserObservationEnabled: currentConfig.browserObservationEnabled &&
+                        currentConfig.browserCdpEndpoints.length > 0 &&
+                        currentConfig.browserAllowedOrigins.length > 0,
                 }),
             });
             liveServers.add(server);

package/dist/native/CommandRunner.js

@@ -16,7 +16,11 @@ export class NativeCommandFailure extends Error {
 }
 /** Run allowlisted Xcode tools directly with bounded output and no shell. */
 export class XcrunCommandRunner {
+    resolveTool;
     #resolved = new Map();
+    constructor(resolveTool = (tool) => resolveXcrunTool(tool)) {
+        this.resolveTool = resolveTool;
+    }
     run(tool, arguments_, options) {
         if (!ALLOWED_TOOLS.has(tool))
             return Promise.resolve(err(new NativeCommandFailure(tool, "unavailable")));
@@ -37,13 +41,16 @@ export class XcrunCommandRunner {
                 : captured;
         });
     }
-    #resolve(tool) {
+    async #resolve(tool) {
         const existing = this.#resolved.get(tool);
         if (existing !== undefined)
             return existing;
-        const pending = resolveTool(tool);
+        const pending = this.resolveTool(tool);
         this.#resolved.set(tool, pending);
-        return pending;
+        const resolved = await pending;
+        if (!resolved.ok && this.#resolved.get(tool) === pending)
+            this.#resolved.delete(tool);
+        return resolved;
     }
 }
 const ALLOWED_TOOLS = new Set([
@@ -59,7 +66,7 @@ const ALLOWED_TOOLS = new Set([
     "swift-demangle",
     "vtool",
 ]);
-const resolveTool = async (tool) => {
+const resolveXcrunTool = async (tool) => {
     const found = await captureProcess("/usr/bin/xcrun", ["--find", tool], "xcrun", { timeoutMs: 5_000, maxOutputBytes: 64 * 1024 });
     if (!found.ok || found.value.exitCode !== 0)
         return err(new NativeCommandFailure(tool, "unavailable"));

package/dist/server/createServer.js

@@ -9,6 +9,7 @@ import { silentLogger } from "../logger.js";
 import { registerGuidedPrompts } from "./registerPrompts.js";
 import { registerEvidenceResources } from "./registerEvidenceResources.js";
 import { createServerIdentity } from "../serverIdentity.js";
+import { registerBrowserTools } from "./registerBrowserTools.js";
 /**
  * Construct one MCP server without acquiring subprocess resources.
  * Supplying a session adds target lifecycle tools; omitting it retains the
@@ -93,6 +94,12 @@ export const createServer = (analysis, session, options = {}) => {
             ? {}
             : { permissionAuthority: options.permissionAuthority }),
     });
+    registerBrowserTools(server, {
+        logger: toolLogger,
+        browser: options.browserObservation,
+        permissionAuthority: options.permissionAuthority,
+        recordEvidence,
+    });
     registerGuidedPrompts(server, analysis, session);
     if (session !== undefined) {
         registerEvidenceResources(server, session);

package/dist/server/registerBrowserTools.js

@@ -0,0 +1,36 @@
+import { inspectWebPage, listBrowserTargets, } from "../application/BrowserObservationService.js";
+import { BROWSER_TOOL_CONTRACTS } from "../contracts/browserToolContracts.js";
+import { inspectWebPageInputSchema, listBrowserTargetsInputSchema, } from "../domain/browserObservation.js";
+import { logToolExecution } from "./toolLogging.js";
+import { toCallToolResult } from "./toolResult.js";
+import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
+import { mcpProgressReporter } from "./mcpProgress.js";
+/** Register browser tools even when policy/provider availability denies execution. */
+export const registerBrowserTools = (server, options) => {
+    const [listContract, inspectContract] = BROWSER_TOOL_CONTRACTS;
+    server.registerTool(listContract.name, toolRegistrationOptions(listContract), async (input, context) => {
+        const parsed = listBrowserTargetsInputSchema.parse(input);
+        const result = await logToolExecution(options.logger, listContract.name, () => listBrowserTargets(options.browser, 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 = inspectWebPageInputSchema.parse(input);
+        const result = await logToolExecution(options.logger, inspectContract.name, () => inspectWebPage(options.browser, 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, contract, evidence) => {
+    const recorded = options.recordEvidence?.(evidence);
+    return recorded !== undefined && !recorded.ok
+        ? toCallToolResult(recorded, contract)
+        : toCallToolResult({ ok: true, value: evidence }, contract, {
+            evidenceResourcesAvailable: recorded !== undefined,
+        });
+};

package/dist/server/registerInvestigationTools.js

@@ -10,9 +10,9 @@ import { err, ok } from "../domain/result.js";
 import { CALL_PATH_PROVIDER, CHANGED_BEHAVIOR_PROVIDER, RECONSTRUCTION_PROVIDER, STATIC_RUNTIME_PROVIDER, } from "./sessionToolPolicies.js";
 import { toCallToolResult } from "./toolResult.js";
 import { recordDerivedEvidence } from "./recordDerivedEvidence.js";
-import { AnalysisProtocolError, PermissionRequiredError, } from "../domain/errors.js";
 import { mcpProgressReporter } from "./mcpProgress.js";
 import { runDerivedOperation } from "./runDerivedOperation.js";
+import { authorizeFileReadWithDeferredWrite, authorizeRootPermission, } from "../application/DeferredFileAuthorization.js";
 /** Register Evidence-composed differential investigation workflows. */
 export const registerInvestigationTools = (server, session, contracts, policies) => {
     registerChangedBehavior(server, session, contracts[0], policies);
@@ -33,42 +33,37 @@ const registerChangedBehavior = (server, session, contract, policies) => {
         const parsed = changedBehaviorInputSchema.parse(input);
         if (parsed.investigation_run !== undefined) {
             const progress = mcpProgressReporter(context);
+            let workspaceAuthorization;
             if (policies.permissionAuthority !== undefined) {
-                const scopes = [
-                    {
-                        capability: "investigation_workspace_read",
-                        roots: [parsed.investigation_run.workspace_path],
-                    },
-                    {
-                        capability: "investigation_workspace_write",
-                        roots: [parsed.investigation_run.workspace_path],
-                    },
-                    {
-                        capability: "investigation_input",
-                        roots: [
-                            parsed.investigation_run.left_path,
-                            parsed.investigation_run.right_path,
-                        ],
-                    },
-                ];
-                for (const scope of scopes) {
-                    const authorized = await policies.permissionAuthority.authorize({
-                        ...scope,
-                        executables: [],
-                        environment_names: [],
-                        network: "none",
-                        mount: false,
-                        operation_identity: `${contract.name}:${scope.capability}:${scope.roots.join(":")}`,
-                    }, scope.capability === "investigation_input" ? "read" : "write");
-                    if (!authorized.ok)
-                        return toCallToolResult(err(authorized.error instanceof PermissionRequiredError
-                            ? authorized.error
-                            : new AnalysisProtocolError(authorized.error.message, {
-                                cause: authorized.error,
-                            })), contract);
-                }
+                const authorizedWorkspace = await authorizeFileReadWithDeferredWrite(policies.permissionAuthority, {
+                    path: parsed.investigation_run.workspace_path,
+                    readCapability: "investigation_workspace_read",
+                    writeCapability: "investigation_workspace_write",
+                    operation: contract.name,
+                });
+                if (!authorizedWorkspace.ok)
+                    return toCallToolResult(authorizedWorkspace, contract);
+                workspaceAuthorization = authorizedWorkspace.value;
+                const authorizedInput = await authorizeRootPermission(policies.permissionAuthority, {
+                    capability: "investigation_input",
+                    roots: [
+                        parsed.investigation_run.left_path,
+                        parsed.investigation_run.right_path,
+                    ],
+                    access: "read",
+                    operation: contract.name,
+                });
+                if (!authorizedInput.ok)
+                    return toCallToolResult(authorizedInput, contract);
             }
-            const investigated = await runCrossVersionInvestigation(parsed.investigation_run, policies.evidenceFiles, investigationExecution(session, context.mcpReq.signal, policies.inputRoots, policies.integrityContinueEnabled?.() ?? false, progress));
+            const investigated = await runCrossVersionInvestigation(parsed.investigation_run, policies.evidenceFiles, {
+                ...investigationExecution(session, context.mcpReq.signal, policies.inputRoots, policies.integrityContinueEnabled?.() ?? false, progress),
+                ...(workspaceAuthorization === undefined
+                    ? {}
+                    : {
+                        authorizeWorkspaceWrite: workspaceAuthorization.authorizeWrite,
+                    }),
+            });
             if (!investigated.ok)
                 return toCallToolResult(investigated, contract);
             const workspace = investigated.value.workspace;

package/dist/server/registerProcessComparisonTool.js

@@ -95,10 +95,12 @@ const comparisonUnknownInput = (parsed, comparison) => {
         return undefined;
     const differingScopes = [
         ["terminal", comparison.terminal],
+        ["interaction", comparison.interaction],
         ["exit", comparison.exit],
         ["filesystem", comparison.filesystem],
         ["protocol", comparison.protocol],
         ["process", comparison.process],
+        ["shim", comparison.shim],
     ]
         .filter(([, status]) => status !== "unchanged")
         .map(([scope]) => scope)

package/dist/server/registerSessionTools.js

@@ -170,6 +170,8 @@ const registerEvidenceTools = ({ server, session, exportContract, importContract
         if (!loaded.ok)
             return toCallToolResult(loaded, importContract);
         const imported = session.importEvidenceBundle(loaded.value);
+        if (imported.ok && imported.value > 0)
+            server.sendResourceListChanged();
         return imported.ok
             ? toCallToolResult(ok({
                 imported: imported.value,
@@ -213,13 +215,23 @@ const registerUnknownTools = ({ server, session, contracts: [listContract, recor
         inputSchema: recordContract.inputSchema,
         outputSchema: recordContract.outputSchema,
         annotations: recordContract.annotations,
-    }, (input) => toCallToolResult(session.recordUnknown(recordUnknownInputSchema.parse(input)), recordContract));
+    }, (input) => {
+        const recorded = session.recordUnknown(recordUnknownInputSchema.parse(input));
+        if (recorded.ok)
+            server.sendResourceListChanged();
+        return toCallToolResult(recorded, recordContract);
+    });
     server.registerTool(updateContract.name, {
         description: updateContract.description,
         inputSchema: updateContract.inputSchema,
         outputSchema: updateContract.outputSchema,
         annotations: updateContract.annotations,
-    }, (input) => toCallToolResult(session.updateUnknown(updateUnknownInputSchema.parse(input)), updateContract));
+    }, (input) => {
+        const updated = session.updateUnknown(updateUnknownInputSchema.parse(input));
+        if (updated.ok)
+            server.sendResourceListChanged();
+        return toCallToolResult(updated, updateContract);
+    });
     server.registerTool(verifyContract.name, {
         description: verifyContract.description,
         inputSchema: verifyContract.inputSchema,
@@ -342,6 +354,7 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
             (() => ({
                 processCaptureEnabled: processPolicy.enabled,
                 evidenceFileRoots: evidenceFilePolicy.roots.length,
+                browserObservationEnabled: false,
             })),
         ...(options.permissionAuthority === undefined
             ? {}

package/dist/server/runDerivedOperation.js

@@ -1,5 +1,5 @@
 import { setImmediate } from "node:timers/promises";
-import { AnalysisCancelledError } from "../domain/errors.js";
+import { AnalysisCancelledError, AnalysisInputError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { mcpProgressReporter } from "./mcpProgress.js";
 /** Run synchronous derived work with transport yields and a publication guard. */
@@ -14,7 +14,15 @@ export const runDerivedOperation = async (context, operation, compute) => {
     await setImmediate();
     if (context.mcpReq.signal.aborted)
         return err(new AnalysisCancelledError(operation));
-    const value = compute();
+    let value;
+    try {
+        value = compute();
+    }
+    catch (cause) {
+        return err(cause instanceof AnalysisCancelledError
+            ? cause
+            : new AnalysisInputError(operation, { cause }));
+    }
     await progress.report({
         phase: "compute",
         completed: 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rea-agents",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Reverse engineer anything from your terminal or agent with one CLI and MCP server.",
   "license": "MIT",
   "repository": {
@@ -70,6 +70,7 @@
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "verify:hopper": "npm run build && node scripts/verify-real-hopper.mjs",
+    "verify:browser": "npm run build && node scripts/verify-real-browser.mjs",
     "verify:hopper:linux": "npm run build && node scripts/verify-real-hopper-linux.mjs",
     "verify:setup:linux": "npm run build && node scripts/verify-linux-setup-e2e.mjs",
     "build:fixtures": "node scripts/build-conformance-fixtures.mjs",

package/scripts/rea.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // Route production MCP before importing Incur. Incur owns registration helpers
-// such as `mcp add`, while only dist/main.js may serve the 68-tool stdio server.
+// such as `mcp add`, while only dist/main.js may serve the 70-tool stdio server.
 const args = process.argv.slice(2);
 const { default: packageJson } = await import("../package.json", {
   with: { type: "json" },

package/skills/rea-analysis/SKILL.md

@@ -1,15 +1,30 @@
 ---
 name: rea-analysis
-description: Reverse engineer apps with REA. Explore how features work, then build a version tailored to your project.
+description: Reverse engineer apps and websites with REA. Explore how features work, then build a version tailored to your project.
 metadata:
-  version: "12"
-  tool_count: 68
+  version: "13"
+  tool_count: 70
 ---
 
 # REA
 
 Use REA when the user wants to understand how an app or feature works, compare app versions, decompile code, or build a similar feature.
 
+For a website already open in a user-owned Chrome-family browser, use
+`list_browser_targets` and `inspect_web_page` instead of opening a binary. Ask
+the user to approve the exact page origins and loopback CDP endpoint before the
+first call. Browser observation is disabled unless the operator configured
+`REA_BROWSER_OBSERVE_ENABLED`, `REA_BROWSER_CDP_ENDPOINTS_JSON`, and
+`REA_BROWSER_ALLOWED_ORIGINS_JSON` before starting REA.
+
+Browser inspection is passive. Never claim that it clicked, navigated,
+evaluated page JavaScript, captured prior activity, or contained the page's
+network. Query values, headers, bodies, cookies, storage values, console values,
+and WebSocket payloads are deliberately absent. Request script sources or
+storage key names only when the user separately approves those more sensitive
+outputs. Treat truncation and attach-window coverage as explicit limitations,
+and cite the returned Evidence v2 IDs.
+
 ## Understand the request
 
 Identify the app and what the user wants to understand or build. Do not ask for information they already provided.