rea-agents 3.0.0 → 3.1.0

package/dist/cliElectronCommands.js

@@ -1,12 +1,15 @@
 import { Cli, z } from "incur";
 import { inspectElectronPage, listElectronTargets, } from "./application/ElectronObservationService.js";
+import { captureElectronScenario } from "./application/ElectronActiveObservationService.js";
 import { reconcileJavaScriptRuntimeEvidence } from "./application/JavaScriptRuntimeReconciliationService.js";
 import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
 import { CdpElectronProvider } from "./browser/CdpElectronProvider.js";
+import { PlaywrightElectronActiveProvider } from "./browser/PlaywrightElectronActiveProvider.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 { electronActiveObservationInputSchema } from "./domain/electronActiveObservation.js";
+import { AnalysisCapabilityUnavailableError, AnalysisInputError, projectAnalysisError, } from "./domain/errors.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
 import { parseCliJsonInput } from "./cliJsonInput.js";
 import { electronPageInspectionOptions, javascriptApplicationOptions, } from "./cliObservationOptions.js";
@@ -21,9 +24,33 @@ const scopeOptions = {
 /** Register CLI equivalents of the Electron MCP tools. */
 export const registerElectronCommands = (cli, logger) => {
     registerElectronObservationCommands(cli, logger);
+    registerElectronActiveCommand(cli, logger);
     registerJavaScriptApplicationCommand(cli, logger);
     registerJavaScriptRuntimeReconciliationCommand(cli, logger);
 };
+const registerElectronActiveCommand = (cli, logger) => {
+    cli.command(CLI_COMMANDS.captureElectronScenario, {
+        description: "Run one approved, bounded owned Electron scenario",
+        args: z.object({
+            inputJson: z
+                .string()
+                .describe("Inline JSON or a JSON file matching capture_electron_scenario"),
+        }),
+        run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.captureElectronScenario, async () => {
+            const input = await parseCliJsonInput(args.inputJson, "capture_electron_scenario");
+            if (!input.ok)
+                return input.error;
+            const parsed = electronActiveObservationInputSchema.safeParse(input.value);
+            if (!parsed.success)
+                return inputError("capture_electron_scenario");
+            const context = await electronContext();
+            if (!context.ok)
+                return context.error;
+            const result = await captureElectronScenario(context.activeProvider, context.authority, parsed.data);
+            return result.ok ? result.value : cliError(result.error);
+        }),
+    });
+};
 const registerJavaScriptRuntimeReconciliationCommand = (cli, logger) => {
     cli.command(CLI_COMMANDS.reconcileJavaScriptRuntime, {
         description: "Reconcile static application and passive runtime Evidence JSON",
@@ -70,7 +97,7 @@ const registerElectronTargetList = (cli, logger) => {
                 .describe("Maximum Electron targets to return"),
         }),
         run: ({ args, options }) => logCliCommand(logger, "list-electron-targets", async () => {
-            const context = await electronContext();
+            const context = await electronObservationContext("list_electron_targets");
             if (!context.ok)
                 return context.error;
             const parsed = listElectronTargetsInputSchema.safeParse({
@@ -98,7 +125,7 @@ const registerElectronPageInspection = (cli, logger) => {
         }),
         options: electronPageInspectionOptions,
         run: ({ args, options }) => logCliCommand(logger, "inspect-electron-page", async () => {
-            const context = await electronContext();
+            const context = await electronObservationContext("inspect_electron_page");
             if (!context.ok)
                 return context.error;
             const parsed = inspectElectronPageInputSchema.safeParse({
@@ -168,7 +195,22 @@ const electronContext = async () => {
         ok: true,
         authority: authority.value,
         provider: new CdpElectronProvider(),
-        allowedFileRoots: config.value.electronFileRoots,
+        activeProvider: new PlaywrightElectronActiveProvider(),
+        observationPolicy: config.value.electronObservationPolicy,
+    };
+};
+const electronObservationContext = async (operation) => {
+    const context = await electronContext();
+    if (!context.ok)
+        return context;
+    if (context.observationPolicy.status === "disabled")
+        return {
+            ok: false,
+            error: cliError(new AnalysisCapabilityUnavailableError("rea-cdp-electron", operation, "Electron observation is disabled; configure exact endpoints and file roots before enabling it")),
+        };
+    return {
+        ...context,
+        allowedFileRoots: context.observationPolicy.fileRoots,
     };
 };
 const inputError = (operation) => cliError(new AnalysisInputError(operation));

package/dist/cliJavaScriptRuntimeCommands.js

@@ -5,8 +5,9 @@ import { V8InspectorProvider } from "./browser/V8InspectorProvider.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
 import { logCliCommand } from "./cliLogging.js";
 import { parseConfig } from "./config.js";
+import { v8InspectorLocationScopes } from "./config/passiveObservation.js";
 import { javascriptRuntimeKindSchema, listJavaScriptRuntimeTargetsInputSchema, observeJavaScriptRuntimeInputSchema, } from "./domain/javascriptRuntimeObservation.js";
-import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+import { AnalysisCapabilityUnavailableError, AnalysisInputError, projectAnalysisError, } from "./domain/errors.js";
 const scopeOptions = {
     allowedFileRoots: z
         .array(z.string().min(1))
@@ -89,7 +90,7 @@ export const registerJavaScriptRuntimeObservationCommands = (cli, logger) => {
         }),
         options: listOptionsSchema,
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.listJavaScriptRuntimeTargets, async () => {
-            const context = await runtimeContext();
+            const context = await runtimeContext("list_javascript_runtime_targets");
             if (!context.ok)
                 return context.error;
             const parsed = listJavaScriptRuntimeTargetsInputSchema.safeParse({
@@ -116,7 +117,7 @@ export const registerJavaScriptRuntimeObservationCommands = (cli, logger) => {
         }),
         options: observeOptionsSchema,
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.observeJavaScriptRuntime, async () => {
-            const context = await runtimeContext();
+            const context = await runtimeContext("observe_javascript_runtime");
             if (!context.ok)
                 return context.error;
             const parsed = observeJavaScriptRuntimeInputSchema.safeParse({
@@ -142,19 +143,26 @@ export const registerJavaScriptRuntimeObservationCommands = (cli, logger) => {
         }),
     });
 };
-const runtimeContext = async () => {
+const runtimeContext = async (operation) => {
     const config = parseConfig(process.env);
     if (!config.ok)
         return { ok: false, error: cliError(config.error) };
+    const policy = config.value.v8InspectorObservationPolicy;
+    if (policy.status === "disabled")
+        return {
+            ok: false,
+            error: cliError(new AnalysisCapabilityUnavailableError("rea-v8-inspector", operation, "V8 Inspector observation is disabled; configure exact endpoints and file or origin scopes before enabling it")),
+        };
     const authority = await loadConfiguredPermissionAuthority(config.value);
     if (!authority.ok)
         return { ok: false, error: cliError(authority.error) };
+    const scopes = v8InspectorLocationScopes(policy.locations);
     return {
         ok: true,
         authority: authority.value,
         provider: new V8InspectorProvider(),
-        allowedFileRoots: config.value.v8InspectorFileRoots,
-        allowedOrigins: config.value.v8InspectorAllowedOrigins,
+        allowedFileRoots: scopes.fileRoots,
+        allowedOrigins: scopes.allowedOrigins,
     };
 };
 const inputError = (operation) => cliError(new AnalysisInputError(operation));

package/dist/cliObservationOptions.js

@@ -50,6 +50,10 @@ export const browserPageInspectionOptions = z.object({
         .boolean()
         .default(false)
         .describe("Include bounded JavaScript source text"),
+    sourceCaptureApproved: z
+        .boolean()
+        .default(false)
+        .describe("Approve capturing bounded script source text"),
     includeStorageKeys: z
         .boolean()
         .default(false)

package/dist/cliPolicyCommands.js

@@ -11,6 +11,7 @@ const capabilitySchema = z.enum([
     "browser_observe",
     "browser_automate",
     "electron_observe",
+    "electron_automate",
     "evidence_read",
     "evidence_write",
     "investigation_input",

package/dist/config/browserScenario.js

@@ -0,0 +1,77 @@
+import { ConfigurationError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { browserEndpointSchema, browserOriginSchema, } from "../domain/browserObservation.js";
+import { parseAbsoluteRoots, parseBrowserArray, parseStringArray, } from "./parsers.js";
+import { browserNetworkScope, permissionScope } from "./permissions.js";
+/** Parse controlled browser scenarios into a closed disabled or enabled policy. */
+export const parseBrowserScenarioPolicy = (env) => {
+    const executableRoots = parseAbsoluteRoots(env.REA_BROWSER_SCENARIO_EXECUTABLE_ROOTS_JSON, "REA_BROWSER_SCENARIO_EXECUTABLE_ROOTS_JSON");
+    if (!executableRoots.ok)
+        return executableRoots;
+    const cdpEndpoints = parseBrowserArray(env.REA_BROWSER_SCENARIO_CDP_ENDPOINTS_JSON, "REA_BROWSER_SCENARIO_CDP_ENDPOINTS_JSON", browserEndpointSchema, 16);
+    if (!cdpEndpoints.ok)
+        return cdpEndpoints;
+    const allowedOrigins = parseBrowserArray(env.REA_BROWSER_SCENARIO_ALLOWED_ORIGINS_JSON, "REA_BROWSER_SCENARIO_ALLOWED_ORIGINS_JSON", browserOriginSchema, 32);
+    if (!allowedOrigins.ok)
+        return allowedOrigins;
+    const allowedEnvironment = parseStringArray(env.REA_BROWSER_SCENARIO_ALLOWED_ENV_JSON, "REA_BROWSER_SCENARIO_ALLOWED_ENV_JSON");
+    if (!allowedEnvironment.ok)
+        return allowedEnvironment;
+    if (env.REA_BROWSER_SCENARIO_ENABLED !== "true")
+        return ok({ status: "disabled" });
+    const [firstOrigin, ...remainingOrigins] = allowedOrigins.value;
+    if (firstOrigin === undefined)
+        return err(new ConfigurationError("REA_BROWSER_SCENARIO_ALLOWED_ORIGINS_JSON must encode at least one exact origin when browser scenarios are enabled"));
+    const target = parseTargetPolicy(executableRoots.value, cdpEndpoints.value);
+    if (!target.ok)
+        return target;
+    return ok({
+        status: "enabled",
+        target: target.value,
+        allowedOrigins: [firstOrigin, ...remainingOrigins],
+        allowedEnvironment: allowedEnvironment.value,
+    });
+};
+/** Add the separately permissioned controlled-browser ceiling. */
+export const appendBrowserScenarioCeiling = (ceilings, policy) => {
+    if (policy.status === "disabled")
+        return;
+    const { executableRoots, cdpEndpoints } = targetScopes(policy.target);
+    ceilings.push(permissionScope("browser_automate", [], {
+        executables: executableRoots,
+        environment_names: policy.allowedEnvironment,
+        origins: [...cdpEndpoints, ...policy.allowedOrigins],
+        network: browserNetworkScope(policy.allowedOrigins),
+    }));
+};
+const parseTargetPolicy = (executableRoots, cdpEndpoints) => {
+    const [firstExecutableRoot, ...remainingExecutableRoots] = executableRoots;
+    const [firstCdpEndpoint, ...remainingCdpEndpoints] = cdpEndpoints;
+    if (firstExecutableRoot !== undefined && firstCdpEndpoint !== undefined)
+        return ok({
+            access: "launch-or-attach",
+            executableRoots: [firstExecutableRoot, ...remainingExecutableRoots],
+            cdpEndpoints: [firstCdpEndpoint, ...remainingCdpEndpoints],
+        });
+    if (firstExecutableRoot !== undefined)
+        return ok({
+            access: "launch",
+            executableRoots: [firstExecutableRoot, ...remainingExecutableRoots],
+        });
+    if (firstCdpEndpoint !== undefined)
+        return ok({
+            access: "attach",
+            cdpEndpoints: [firstCdpEndpoint, ...remainingCdpEndpoints],
+        });
+    return err(new ConfigurationError("Browser scenarios require at least one executable root or loopback CDP endpoint when enabled"));
+};
+const targetScopes = (target) => {
+    switch (target.access) {
+        case "launch":
+            return { executableRoots: target.executableRoots, cdpEndpoints: [] };
+        case "attach":
+            return { executableRoots: [], cdpEndpoints: target.cdpEndpoints };
+        case "launch-or-attach":
+            return target;
+    }
+};

package/dist/config/electronAutomation.js

@@ -0,0 +1,35 @@
+import { ConfigurationError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { permissionScope } from "./permissions.js";
+import { parseAbsoluteRoots } from "./parsers.js";
+/** Parse active Electron automation into a closed disabled or enabled policy. */
+export const parseElectronAutomationPolicy = (env) => {
+    const executableRoots = parseAbsoluteRoots(env.REA_ELECTRON_AUTOMATE_EXECUTABLE_ROOTS_JSON, "REA_ELECTRON_AUTOMATE_EXECUTABLE_ROOTS_JSON");
+    if (!executableRoots.ok)
+        return executableRoots;
+    const applicationRoots = parseAbsoluteRoots(env.REA_ELECTRON_AUTOMATE_APPLICATION_ROOTS_JSON, "REA_ELECTRON_AUTOMATE_APPLICATION_ROOTS_JSON");
+    if (!applicationRoots.ok)
+        return applicationRoots;
+    if (env.REA_ELECTRON_AUTOMATE_ENABLED !== "true")
+        return ok({ status: "disabled" });
+    const [firstExecutableRoot, ...remainingExecutableRoots] = executableRoots.value;
+    if (firstExecutableRoot === undefined)
+        return err(new ConfigurationError("REA_ELECTRON_AUTOMATE_EXECUTABLE_ROOTS_JSON must encode at least one absolute root when Electron automation is enabled"));
+    const [firstApplicationRoot, ...remainingApplicationRoots] = applicationRoots.value;
+    if (firstApplicationRoot === undefined)
+        return err(new ConfigurationError("REA_ELECTRON_AUTOMATE_APPLICATION_ROOTS_JSON must encode at least one absolute root when Electron automation is enabled"));
+    return ok({
+        status: "enabled",
+        executableRoots: [firstExecutableRoot, ...remainingExecutableRoots],
+        applicationRoots: [firstApplicationRoot, ...remainingApplicationRoots],
+    });
+};
+/** Add the separately permissioned, no-network Electron automation ceiling. */
+export const appendElectronAutomationCeiling = (ceilings, policy) => {
+    if (policy.status === "disabled")
+        return;
+    ceilings.push(permissionScope("electron_automate", policy.applicationRoots, {
+        executables: policy.executableRoots,
+        network: "external",
+    }));
+};

package/dist/config/environment.js

@@ -61,6 +61,12 @@ const environmentSchema = z
     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_ELECTRON_AUTOMATE_ENABLED: z.enum(["true", "false"]).default("false"),
+    REA_ELECTRON_AUTOMATE_AUTO_GRANT: z
+        .enum(["true", "false"])
+        .default("false"),
+    REA_ELECTRON_AUTOMATE_EXECUTABLE_ROOTS_JSON: z.string().default("[]"),
+    REA_ELECTRON_AUTOMATE_APPLICATION_ROOTS_JSON: z.string().default("[]"),
     REA_V8_INSPECTOR_OBSERVE_ENABLED: z
         .enum(["true", "false"])
         .default("false"),

package/dist/config/javascriptReplay.js

@@ -0,0 +1,41 @@
+import { ConfigurationError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { parseAbsoluteRoots } from "./parsers.js";
+import { permissionScope } from "./permissions.js";
+/** Parse controlled replay configuration into disabled or fully enabled state. */
+export const parseJavaScriptReplayPolicy = (env) => {
+    const roots = parseAbsoluteRoots(env.REA_JAVASCRIPT_REPLAY_ROOTS_JSON, "REA_JAVASCRIPT_REPLAY_ROOTS_JSON");
+    if (!roots.ok)
+        return roots;
+    if (env.REA_JAVASCRIPT_REPLAY_ENABLED !== "true")
+        return ok({ status: "disabled" });
+    const [firstRoot, ...remainingRoots] = roots.value;
+    if (firstRoot === undefined)
+        return err(new ConfigurationError("REA_JAVASCRIPT_REPLAY_ROOTS_JSON must encode at least one absolute root when JavaScript replay is enabled"));
+    return ok({
+        status: "enabled",
+        roots: [firstRoot, ...remainingRoots],
+        nodePath: env.REA_JAVASCRIPT_REPLAY_NODE_PATH,
+        bubblewrapPath: env.REA_JAVASCRIPT_REPLAY_BWRAP_PATH,
+        systemdRunPath: env.REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH,
+        systemctlPath: env.REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH,
+        shellPath: env.REA_JAVASCRIPT_REPLAY_SHELL_PATH,
+    });
+};
+/** Add the exact controlled replay ceiling when replay is enabled. */
+export const appendJavaScriptReplayCeiling = (ceilings, policy) => {
+    if (policy.status === "disabled")
+        return;
+    ceilings.push(permissionScope("javascript_replay", policy.roots, {
+        executables: replayExecutables(policy),
+        network: "none",
+        mount: true,
+    }));
+};
+const replayExecutables = (policy) => [
+    policy.nodePath,
+    policy.bubblewrapPath,
+    policy.systemdRunPath,
+    policy.systemctlPath,
+    policy.shellPath,
+];

package/dist/config/managedRuntime.js

@@ -0,0 +1,25 @@
+import { ConfigurationError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { permissionScope } from "./permissions.js";
+/** Parse managed runtime correlation into a closed disabled or enabled policy. */
+export const parseManagedRuntimePolicy = (env, roots) => {
+    if (env.REA_MANAGED_RUNTIME_ENABLED !== "true")
+        return ok({ status: "disabled" });
+    const [firstRoot, ...remainingRoots] = roots;
+    if (firstRoot === undefined)
+        return err(new ConfigurationError("REA_MANAGED_RUNTIME_ROOTS_JSON must encode at least one absolute root when managed runtime correlation is enabled"));
+    return ok({
+        status: "enabled",
+        roots: [firstRoot, ...remainingRoots],
+        executablePath: env.REA_MANAGED_RUNTIME_EXECUTABLE_PATH,
+    });
+};
+/** Add the separately permissioned, no-network managed runtime ceiling. */
+export const appendManagedRuntimeCeiling = (ceilings, policy) => {
+    if (policy.status === "disabled")
+        return;
+    ceilings.push(permissionScope("managed_runtime", policy.roots, {
+        executables: [policy.executablePath],
+        network: "none",
+    }));
+};