rea-agents 1.4.0 → 1.5.0

package/dist/cliBrowserCommands.js

@@ -0,0 +1,136 @@
+import { Cli, z } from "incur";
+import { inspectWebPage, listBrowserTargets, } 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 { inspectWebPageInputSchema, listBrowserTargetsInputSchema, } from "./domain/browserObservation.js";
+import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+const browserScopeOptions = {
+    allowedOrigins: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Exact origins to observe; defaults to REA_BROWSER_ALLOWED_ORIGINS_JSON"),
+    approved: z.boolean().default(false).describe("Approve passive observation"),
+};
+/** Register CLI equivalents of the passive browser MCP tools. */
+export const registerBrowserCommands = (cli, logger) => {
+    registerTargetList(cli, logger);
+    registerPageInspection(cli, logger);
+};
+const registerTargetList = (cli, logger) => {
+    cli.command("list-browser-targets", {
+        description: "List approved pages from a user-owned loopback CDP browser",
+        args: z.object({
+            endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+        }),
+        options: z.object({
+            ...browserScopeOptions,
+            offset: z.number().int().min(0).default(0),
+            limit: z.number().int().min(1).max(200).default(100),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, "list-browser-targets", async () => {
+            const context = await browserContext();
+            if (!context.ok)
+                return context.error;
+            const parsed = listBrowserTargetsInputSchema.safeParse({
+                cdp_endpoint: args.endpoint,
+                allowed_origins: options.allowedOrigins ?? context.allowedBrowserOrigins,
+                approved: options.approved,
+                offset: options.offset,
+                limit: options.limit,
+            });
+            if (!parsed.success)
+                return cliError(new AnalysisInputError("list_browser_targets"));
+            const result = await listBrowserTargets(context.provider, context.authority, parsed.data);
+            return result.ok ? result.value : cliError(result.error);
+        }),
+    });
+};
+const registerPageInspection = (cli, logger) => {
+    cli.command("inspect-web-page", {
+        description: "Passively inspect one approved page through CDP",
+        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(0).max(10_000).default(500),
+            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),
+            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),
+            maxStorageKeys: z.number().int().min(1).max(10_000).default(1_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),
+            maxNetworkEvents: z.number().int().min(1).max(10_000).default(1_000),
+            maxConsoleEvents: z.number().int().min(1).max(2_000).default(200),
+            maxWebsocketEvents: z.number().int().min(1).max(5_000).default(500),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, "inspect-web-page", async () => {
+            const context = await browserContext();
+            if (!context.ok)
+                return context.error;
+            const parsed = inspectWebPageInputSchema.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: options.includeScriptSources,
+                include_storage_keys: options.includeStorageKeys,
+                limits: {
+                    max_frames: options.maxFrames,
+                    max_dom_nodes: options.maxDomNodes,
+                    max_ax_nodes: options.maxAxNodes,
+                    max_scripts: options.maxScripts,
+                    max_resources: options.maxResources,
+                    max_workers: options.maxWorkers,
+                    max_storage_keys: options.maxStorageKeys,
+                    max_script_source_bytes: options.maxScriptSourceBytes,
+                    max_total_script_source_bytes: options.maxTotalScriptSourceBytes,
+                    max_network_events: options.maxNetworkEvents,
+                    max_console_events: options.maxConsoleEvents,
+                    max_websocket_events: options.maxWebsocketEvents,
+                },
+            });
+            if (!parsed.success)
+                return cliError(new AnalysisInputError("inspect_web_page"));
+            const result = await inspectWebPage(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, error: cliError(config.error) };
+    const authority = await loadConfiguredPermissionAuthority(config.value);
+    if (!authority.ok)
+        return { ok: false, error: cliError(authority.error) };
+    return {
+        ok: true,
+        authority: authority.value,
+        provider: new CdpBrowserProvider(),
+        allowedBrowserOrigins: config.value.browserAllowedOrigins,
+    };
+};
+const cliError = (error) => ({
+    error: "Browser observation failed",
+    ...projectAnalysisError(error),
+});

package/dist/cliInvestigationCommands.js

@@ -2,8 +2,9 @@ import { Cli, z } from "incur";
 import { runCrossVersionInvestigation } from "./application/CrossVersionInvestigation.js";
 import { logCliCommand } from "./cliLogging.js";
 import { parseConfig } from "./config.js";
-import { AnalysisProtocolError, PermissionRequiredError, projectAnalysisError, } from "./domain/errors.js";
+import { projectAnalysisError } from "./domain/errors.js";
 import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
+import { authorizeFileReadWithDeferredWrite, authorizeRootPermission, } from "./application/DeferredFileAuthorization.js";
 const investigationOptionsSchema = z.object({
     yes: z
         .boolean()
@@ -68,39 +69,22 @@ const runInvestigation = async (args, options) => {
     const authority = await loadConfiguredPermissionAuthority(config.value);
     if (!authority.ok)
         return cliError(authority.error);
-    for (const scope of [
-        {
-            capability: "investigation_workspace_read",
-            roots: [args.workspacePath],
-            access: "write",
-        },
-        {
-            capability: "investigation_workspace_write",
-            roots: [args.workspacePath],
-            access: "write",
-        },
-        {
-            capability: "investigation_input",
-            roots: [args.leftPath, args.rightPath],
-            access: "read",
-        },
-    ]) {
-        const authorized = await authority.value.authorize({
-            capability: scope.capability,
-            roots: scope.roots,
-            executables: [],
-            environment_names: [],
-            network: "none",
-            mount: false,
-            operation_identity: `investigate_versions:${scope.capability}:${scope.roots.join(":")}`,
-        }, scope.access);
-        if (!authorized.ok)
-            return cliError(authorized.error instanceof PermissionRequiredError
-                ? authorized.error
-                : new AnalysisProtocolError(authorized.error.message, {
-                    cause: authorized.error,
-                }));
-    }
+    const workspaceAuthorization = await authorizeFileReadWithDeferredWrite(authority.value, {
+        path: args.workspacePath,
+        readCapability: "investigation_workspace_read",
+        writeCapability: "investigation_workspace_write",
+        operation: "investigate_versions",
+    });
+    if (!workspaceAuthorization.ok)
+        return cliError(workspaceAuthorization.error);
+    const inputAuthorization = await authorizeRootPermission(authority.value, {
+        capability: "investigation_input",
+        roots: [args.leftPath, args.rightPath],
+        access: "read",
+        operation: "investigate_versions",
+    });
+    if (!inputAuthorization.ok)
+        return cliError(inputAuthorization.error);
     const investigated = await runCrossVersionInvestigation({
         approved: true,
         workspace_path: args.workspacePath,
@@ -126,6 +110,7 @@ const runInvestigation = async (args, options) => {
     }, config.value.evidenceFilePolicy, {
         inputRoots: config.value.investigationInputRoots,
         integrityContinueEnabled: config.value.artifactIntegrityContinueEnabled,
+        authorizeWorkspaceWrite: workspaceAuthorization.value.authorizeWrite,
     });
     return investigated.ok
         ? investigated.value.evidence

package/dist/cliPolicyCommands.js

@@ -1,11 +1,12 @@
 import { Cli, z } from "incur";
 import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
-import { readProjectPermissionStore, writeProjectPermissionStore, } from "./application/ProjectPermissionStore.js";
+import { readProjectPermissionStore, revokeProjectPermissionGrant, } from "./application/ProjectPermissionStore.js";
 import { logCliCommand } from "./cliLogging.js";
 import { parseConfig } from "./config.js";
 import { PermissionRequiredError, projectAnalysisError, } from "./domain/errors.js";
 const capabilitySchema = z.enum([
     "process_capture",
+    "browser_observe",
     "evidence_read",
     "evidence_write",
     "investigation_input",
@@ -29,6 +30,7 @@ export const registerPolicyCommands = (cli, logger) => {
             root: z.string().optional(),
             executable: z.string().optional(),
             environmentNames: z.array(z.string()).default([]),
+            origins: z.array(z.string()).default([]),
             network: z.enum(["none", "loopback", "external"]).default("none"),
             mount: z.boolean().default(false),
             write: z.boolean().default(false),
@@ -50,19 +52,19 @@ export const registerPolicyCommands = (cli, logger) => {
             if (args.action === "revoke") {
                 if (args.value === undefined)
                     return { error: "Grant ID is required for policy revoke" };
-                const result = await readProjectGrants(config.value);
-                if (!result.ok)
-                    return result.error;
-                const retained = result.grants.filter(({ grant_id }) => grant_id !== args.value);
-                if (retained.length === result.grants.length)
-                    return { error: "Grant was not found", grant_id: args.value };
-                const written = await writeProjectPermissionStore(result.path, result.root, retained);
-                return written.ok
+                const { permissionProjectRoot, permissionProjectStore } = config.value;
+                if (permissionProjectRoot === undefined ||
+                    permissionProjectStore === undefined)
+                    return { error: "Project policy is not configured" };
+                const revoked = await revokeProjectPermissionGrant(permissionProjectStore, permissionProjectRoot, args.value);
+                return revoked.ok && revoked.value
                     ? {
                         revoked: args.value,
                         reload: "Send SIGHUP to the REA MCP process",
                     }
-                    : { error: written.error.message };
+                    : revoked.ok
+                        ? { error: "Grant was not found", grant_id: args.value }
+                        : { error: revoked.error.message };
             }
             const capability = capabilitySchema.safeParse(args.value);
             if (!capability.success)
@@ -82,6 +84,7 @@ const explain = async (config, capability, options) => {
         roots: options.root === undefined ? [] : [options.root],
         executables: options.executable === undefined ? [] : [options.executable],
         environment_names: options.environmentNames,
+        origins: options.origins,
         network: options.network,
         mount: options.mount,
         operation_identity: `policy_explain:${capability}`,

package/dist/config.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { ConfigurationError } from "./domain/errors.js";
 import { err, ok } from "./domain/result.js";
+import { browserEndpointSchema, browserOriginSchema, } from "./domain/browserObservation.js";
 const DEFAULT_HOPPER_LAUNCHER_PATH = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
 const defaultHopperLauncherPath = () => process.platform === "linux"
     ? "/opt/hopper/bin/Hopper"
@@ -34,6 +35,9 @@ const environmentSchema = z
     REA_ANALYSIS_SNAPSHOT_ROOTS_JSON: z.string().default("[]"),
     REA_REFERENCE_ROOTS_JSON: z.string().default("[]"),
     REA_REFERENCE_SECRET_PATTERNS_JSON: z.string().default("[]"),
+    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_PERMISSION_PROJECT_ROOT: z.string().min(1).optional(),
     REA_PERMISSION_PROJECT_STORE: z.string().min(1).optional(),
 })
@@ -57,6 +61,22 @@ const parseStringArray = (encoded, name) => {
         return err(new ConfigurationError(`${name} must be valid JSON`, { cause }));
     }
 };
+const parseBrowserArray = (encoded, name, itemSchema, maximum) => {
+    try {
+        const parsed = z
+            .array(itemSchema)
+            .max(maximum)
+            .safeParse(JSON.parse(encoded));
+        return parsed.success
+            ? ok([...new Set(parsed.data)].sort())
+            : err(new ConfigurationError(`${name} must encode valid browser scopes`, {
+                cause: parsed.error,
+            }));
+    }
+    catch (cause) {
+        return err(new ConfigurationError(`${name} must be valid JSON`, { cause }));
+    }
+};
 const filePolicy = (roots) => ({
     roots,
     maxBytes: 64 * 1024 * 1024,
@@ -69,6 +89,7 @@ const permissionScope = (capability, roots, options = {}) => ({
     roots,
     executables: options.executables ?? [],
     environment_names: options.environment_names ?? [],
+    ...(options.origins === undefined ? {} : { origins: options.origins }),
     network: options.network ?? "none",
     mount: options.mount ?? false,
 });
@@ -136,6 +157,12 @@ export const parseConfig = (environment) => {
     const secretPatterns = parseStringArray(parsedEnvironment.data.REA_REFERENCE_SECRET_PATTERNS_JSON, "REA_REFERENCE_SECRET_PATTERNS_JSON");
     if (!secretPatterns.ok)
         return secretPatterns;
+    const browserEndpoints = parseBrowserArray(parsedEnvironment.data.REA_BROWSER_CDP_ENDPOINTS_JSON, "REA_BROWSER_CDP_ENDPOINTS_JSON", browserEndpointSchema, 16);
+    if (!browserEndpoints.ok)
+        return browserEndpoints;
+    const browserOrigins = parseBrowserArray(parsedEnvironment.data.REA_BROWSER_ALLOWED_ORIGINS_JSON, "REA_BROWSER_ALLOWED_ORIGINS_JSON", browserOriginSchema, 32);
+    if (!browserOrigins.ok)
+        return browserOrigins;
     const permissionCeilings = [
         ...(parsedEnvironment.data.REA_PROCESS_CAPTURE_ENABLED === "true"
             ? [
@@ -158,6 +185,14 @@ export const parseConfig = (environment) => {
         permissionScope("snapshot_write", analysisSnapshotRoots.value),
         permissionScope("artifact_extract", ["/"]),
         permissionScope("reference_read", referenceRoots.value),
+        ...(parsedEnvironment.data.REA_BROWSER_OBSERVE_ENABLED === "true"
+            ? [
+                permissionScope("browser_observe", [], {
+                    origins: [...browserEndpoints.value, ...browserOrigins.value],
+                    network: browserNetworkScope(browserOrigins.value),
+                }),
+            ]
+            : []),
         ...(parsedEnvironment.data.REA_ARTIFACT_NATIVE_MOUNT_ENABLED === "true"
             ? [permissionScope("native_mount", [], { mount: true })]
             : []),
@@ -189,9 +224,18 @@ export const parseConfig = (environment) => {
             maxDepth: 32,
             maxPathBytes: 4_096,
         },
+        browserObservationEnabled: parsedEnvironment.data.REA_BROWSER_OBSERVE_ENABLED === "true",
+        browserCdpEndpoints: browserEndpoints.value,
+        browserAllowedOrigins: browserOrigins.value,
         permissionCeilings,
         administratorPermissionGrants: administratorGrants(permissionCeilings),
         permissionProjectRoot: parsedEnvironment.data.REA_PERMISSION_PROJECT_ROOT,
         permissionProjectStore: parsedEnvironment.data.REA_PERMISSION_PROJECT_STORE,
     });
 };
+const browserNetworkScope = (origins) => origins.every((origin) => {
+    const hostname = new URL(origin).hostname;
+    return hostname === "127.0.0.1" || hostname === "[::1]";
+})
+    ? "loopback"
+    : "external";

package/dist/contracts/browserToolContracts.js

@@ -0,0 +1,80 @@
+import { evidenceSchema } from "../domain/evidence.js";
+import { browserTargetListSchema, inspectWebPageInputSchema, listBrowserTargetsInputSchema, webPageInspectionSchema, } from "../domain/browserObservation.js";
+const evidenceResult = (schema) => evidenceSchema
+    .omit({ normalized_result: true })
+    .extend({ normalized_result: schema });
+const listOutputSchema = evidenceResult(browserTargetListSchema);
+const inspectionOutputSchema = evidenceSchema
+    .omit({ normalized_result: true })
+    .extend({ normalized_result: webPageInspectionSchema });
+const endpoint = "http://127.0.0.1:9222";
+const origin = "https://app.example.test";
+/** Origin-scoped, passive browser reverse-engineering contracts. */
+export const BROWSER_TOOL_CONTRACTS = [
+    {
+        name: "list_browser_targets",
+        description: "List bounded page targets from an approved user-owned loopback Chrome DevTools Protocol endpoint. Only targets whose current URL matches an approved exact origin are returned; URL credentials, query values, and fragments are redacted.",
+        kind: "browser-provider",
+        inputSchema: listBrowserTargetsInputSchema,
+        outputSchema: listOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        examples: [
+            {
+                title: "List approved browser page targets",
+                input: {
+                    cdp_endpoint: endpoint,
+                    allowed_origins: [origin],
+                    approved: true,
+                    offset: 0,
+                    limit: 100,
+                },
+            },
+        ],
+    },
+    {
+        name: "inspect_web_page",
+        description: "Passively inspect one approved page target through CDP without evaluating JavaScript, navigating, clicking, closing, or mutating the page. Returns bounded DOM structure, accessibility, scripts, resources, attach-window network and console metadata, workers, and redacted storage inventory as Evidence v2.",
+        kind: "browser-provider",
+        inputSchema: inspectWebPageInputSchema,
+        outputSchema: inspectionOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        examples: [
+            {
+                title: "Inspect one approved browser page",
+                input: {
+                    cdp_endpoint: endpoint,
+                    allowed_origins: [origin],
+                    approved: true,
+                    target_id: "TARGET_ID_FROM_LIST_BROWSER_TARGETS",
+                    observation_ms: 500,
+                    include_script_sources: false,
+                    include_storage_keys: false,
+                    limits: {
+                        max_frames: 200,
+                        max_dom_nodes: 2_000,
+                        max_ax_nodes: 2_000,
+                        max_scripts: 200,
+                        max_resources: 2_000,
+                        max_workers: 500,
+                        max_storage_keys: 1_000,
+                        max_script_source_bytes: 1_048_576,
+                        max_total_script_source_bytes: 4_194_304,
+                        max_network_events: 1_000,
+                        max_console_events: 200,
+                        max_websocket_events: 500,
+                    },
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/errorSchemas.js

@@ -33,6 +33,7 @@ const scopeSchema = z
     roots: z.array(z.string()),
     executables: z.array(z.string()),
     environment_names: z.array(z.string()),
+    origins: z.array(z.string()).optional(),
     network: z.enum(["none", "loopback", "external"]),
     mount: z.boolean(),
 })
@@ -42,6 +43,7 @@ const missingScopeSchema = z
     roots: z.array(z.string()).optional(),
     executables: z.array(z.string()).optional(),
     environment_names: z.array(z.string()).optional(),
+    origins: z.array(z.string()).optional(),
     network: z.enum(["none", "loopback", "external"]).optional(),
     mount: z.literal(true).optional(),
 })

package/dist/contracts/toolContracts.js

@@ -14,6 +14,7 @@ import { enhancedOutputSchemas, officialOutputSchemas, requireOutputSchema, sess
 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 { closeBinaryInputSchema, openBinaryInputSchema, } from "./sessionLifecycleInputs.js";
 const document = z.string().optional().describe("The document name");
 const address = z.string().describe("A Hopper address");
@@ -207,15 +208,12 @@ export const SESSION_TOOL_CONTRACTS = [
     session("update_unknown", "Append one immutable full-state revision and mutation evidence. Requires approved: true and exact expected_revision; stale concurrent writers fail instead of overwriting newer analysis.", updateUnknownInputSchema),
     session("verify_unknown_resolution", "Revalidate the current residual-unknown head against live bundled evidence, exact authority/confidence/environment requirements, and revision integrity. Withdrawn and out-of-scope dispositions are not truth claims.", z.object({ unknown_id: z.string().regex(/^unk_[a-f0-9]{64}$/u) })),
 ];
-/**
- * Complete ordered public inventory used by registration and verification.
- * Keep this collection at 68 tools unless a deliberate contract change updates
- * snapshots, package verification, and real-Hopper verification together.
- */
+/** Complete ordered public inventory used by registration and verification. */
 export const TOOL_CONTRACTS = [
     ...OFFICIAL_TOOL_CONTRACTS,
     ...ENHANCED_TOOL_CONTRACTS,
     ...NATIVE_TOOL_CONTRACTS,
     ...ARTIFACT_TOOL_CONTRACTS,
+    ...BROWSER_TOOL_CONTRACTS,
     ...SESSION_TOOL_CONTRACTS,
 ];