rea-agents 2.5.0 → 3.1.0

package/dist/browser/V8InspectorProvider.js

@@ -3,7 +3,7 @@ import { AnalysisError, BrowserObservationError, ProviderAdapterError, } from ".
 import { err, ok } from "../domain/result.js";
 import { boundedText, numberValue, recordValue, stringValue, delayWithCancellation, } from "./CdpCaptureValues.js";
 import { CdpConnection } from "./CdpConnection.js";
-import { authorizeRuntimeLocation, canonicalRuntimeRoots, } from "./JavaScriptRuntimeScope.js";
+import { authorizeRuntimeTargetLocation, canonicalRuntimeRoots, } from "./JavaScriptRuntimeScope.js";
 import { createInspectorExclusionCounts, describeInspectorTargetLimitations, finalizeInspectorCapture, } from "./V8InspectorCaptureProjection.js";
 import { discoverV8Inspector, } from "./V8InspectorEndpoint.js";
 /** Public identity committed by passive V8 Inspector observations. */
@@ -24,7 +24,7 @@ export class V8InspectorProvider {
             const allowed = [];
             const excluded = createInspectorExclusionCounts();
             for (const target of discovery.targets) {
-                const decision = await authorizeRuntimeLocation(target.url, roots, input.allowed_origins);
+                const decision = await authorizeRuntimeTargetLocation(target.url, target.type, roots, input.allowed_origins);
                 if (!decision.allowed) {
                     excluded[decision.reason] += 1;
                     continue;
@@ -104,7 +104,7 @@ const authorizedTarget = async (targets, input, roots) => {
     const target = targets.find(({ id }) => id === input.target_id);
     if (target === undefined)
         throw new BrowserObservationError("observe_javascript_runtime", "target_not_found");
-    const decision = await authorizeRuntimeLocation(target.url, roots, input.allowed_origins);
+    const decision = await authorizeRuntimeTargetLocation(target.url, target.type, roots, input.allowed_origins);
     if (target.attached ||
         !decision.allowed ||
         decision.location.kind === "builtin")

package/dist/catalogIdentity.js

@@ -12,12 +12,18 @@ const toolCatalog = TOOL_CONTRACTS.map((contract) => ({
     description: contract.description,
     effects: { ...contract.effects },
     annotations: contract.annotations,
-    input_schema: z.toJSONSchema(contract.inputSchema, {
-        unrepresentable: "any",
-    }),
-    output_schema: z.toJSONSchema(contract.outputSchema, {
-        unrepresentable: "any",
-    }),
+    input_schema: {
+        type: "object",
+        ...z.toJSONSchema(contract.inputSchema, {
+            unrepresentable: "any",
+        }),
+    },
+    output_schema: {
+        type: "object",
+        ...z.toJSONSchema(contract.outputSchema, {
+            unrepresentable: "any",
+        }),
+    },
 })).sort((left, right) => left.name.localeCompare(right.name));
 const promptCatalog = PROMPT_CONTRACTS.map((contract) => ({
     name: contract.name,
@@ -29,7 +35,7 @@ const promptCatalog = PROMPT_CONTRACTS.map((contract) => ({
 /** Canonical fixed resources exposed by every target-free MCP session. */
 export const MCP_RESOURCE_CATALOG = [
     { name: "server-identity", uri: "rea://server/identity" },
-    { name: "active-residual-unknowns", uri: "rea://unknowns/active" },
+    { name: "analysis-snapshot", uri: "rea://snapshot/current" },
 ];
 /** Canonical resource templates exposed by every target-free MCP session. */
 export const MCP_RESOURCE_TEMPLATE_CATALOG = [
@@ -40,8 +46,8 @@ export const MCP_RESOURCE_TEMPLATE_CATALOG = [
     },
     { name: "residual-unknown", uri_template: "rea://unknown/{unknownId}" },
     {
-        name: "analysis-snapshot",
-        uri_template: "rea://snapshot/{snapshotDigest}",
+        name: "evidence-bundle",
+        uri_template: "rea://evidence-bundle/{bundleDigest}",
     },
     {
         name: "artifact-page",

package/dist/cli/artifactCommands.js

@@ -73,17 +73,19 @@ const registerExtractionCommand = (cli, logger) => {
         args: z.object({
             path: z.string().describe("Application or package path"),
             outputRoot: z.string().describe("Absent absolute output root"),
+        }),
+        options: z.object({
             occurrenceIds: z
                 .array(z.string().regex(/^occ_[a-f0-9]{64}$/u))
                 .min(1)
                 .max(500)
                 .describe("Exact artifact occurrence IDs selected for extraction"),
         }),
-        alias: { outputRoot: "output-root", occurrenceIds: "occurrence-ids" },
-        run: ({ args }) => logCliCommand(logger, "extract-artifact", () => runProviderAnalysis(args.path, "extract_artifact", {
+        alias: { occurrenceIds: "occurrence-ids" },
+        run: ({ args, options }) => logCliCommand(logger, "extract-artifact", () => runProviderAnalysis(args.path, "extract_artifact", {
             approved: true,
             output_root: args.outputRoot,
-            occurrence_ids: args.occurrenceIds,
+            occurrence_ids: options.occurrenceIds,
         }, logger)),
     });
 };

package/dist/cli/coreAnalysisCommands.js

@@ -9,6 +9,7 @@ import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnal
 export const registerCoreAnalysisCommands = (cli, logger) => {
     registerCoreCommands(cli, logger);
     registerFunctionCommand(cli, logger);
+    registerNativeApiCommand(cli, logger);
     registerInstructionsCommand(cli, logger);
     registerSearchCommand(cli, logger);
     registerXrefsCommand(cli, logger);
@@ -213,6 +214,46 @@ const registerFunctionCommand = (cli, logger) => {
         }, directAnalysisOptions(logger, options.snapshot, options.provider))),
     });
 };
+const registerNativeApiCommand = (cli, logger) => {
+    cli.command(CLI_COMMANDS.inspectNativeApi, {
+        description: "Reconstruct one native function API boundary with evidence",
+        args: z.object({
+            path: z.string().describe("App or program path"),
+            address: z.string().describe("Procedure name or address"),
+        }),
+        options: z.object({
+            maxPseudocodeChars: z
+                .number()
+                .int()
+                .min(1)
+                .max(100_000)
+                .default(20_000)
+                .describe("Maximum pseudocode characters to inspect"),
+            maxInstructions: z
+                .number()
+                .int()
+                .min(1)
+                .max(5_000)
+                .default(500)
+                .describe("Maximum assembly instructions to inspect"),
+            snapshot: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Load and update a local analysis snapshot"),
+            provider: providerSelectionOption,
+        }),
+        alias: {
+            maxPseudocodeChars: "max-pseudocode-chars",
+            maxInstructions: "max-instructions",
+        },
+        run: ({ args, options }) => logCliCommand(logger, "inspect-native-api", () => runDirectAnalysis(args.path, "inspect_native_api", {
+            procedure: args.address,
+            max_pseudocode_chars: options.maxPseudocodeChars,
+            max_instructions: options.maxInstructions,
+        }, directAnalysisOptions(logger, options.snapshot, options.provider))),
+    });
+};
 const registerInstructionsCommand = (cli, logger) => {
     cli.command(CLI_COMMANDS.instructions, {
         description: "Read one bounded raw-instruction window without decompiling",

package/dist/cli/managedCommands.js

@@ -388,7 +388,7 @@ const registerPlanManagedRuntimeCorrelation = (cli, logger) => {
             if (!authority.ok)
                 return projectAnalysisError(authority.error);
             const result = await planManagedRuntimeCorrelationEvidence({
-                policy: config.value.managedRuntimePolicy,
+                policy: () => config.value.managedRuntimePolicy,
                 authority: authority.value,
             }, input.value);
             return result.ok ? result.value : projectAnalysisError(result.error);

package/dist/cliApplicationCommands.js

@@ -75,7 +75,7 @@ export const registerApplicationCommands = (cli, logger) => {
             if (!authority.ok)
                 return projectAnalysisError(authority.error);
             const result = await runControlledReplay({
-                policy: config.value.javascriptReplayPolicy,
+                policy: () => config.value.javascriptReplayPolicy,
                 host: new SystemJavaScriptReplayHost(),
                 runner: new LinuxJavaScriptReplayRunner(),
                 authority: authority.value,
@@ -193,7 +193,7 @@ const configuredAuthority = async () => {
         : { ok: false, error: projectAnalysisError(configured.error) };
 };
 const replayDependencies = (config, authority) => ({
-    policy: config.javascriptReplayPolicy,
+    policy: () => config.javascriptReplayPolicy,
     host: new SystemJavaScriptReplayHost(),
     runner: new LinuxJavaScriptReplayRunner(),
     authority,

package/dist/cliBrowserAdvancedCommands.js

@@ -4,7 +4,7 @@ import { loadConfiguredPermissionAuthority } from "./application/PermissionConfi
 import { CdpBrowserProvider } from "./browser/CdpBrowserProvider.js";
 import { logCliCommand } from "./cliLogging.js";
 import { parseConfig } from "./config.js";
-import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+import { AnalysisCapabilityUnavailableError, AnalysisInputError, projectAnalysisError, } from "./domain/errors.js";
 import { browserCaptureComparisonInputSchema } from "./domain/browserCaptureComparison.js";
 import { discoverWebMcpToolsInputSchema } from "./domain/webMcpDiscovery.js";
 import { captureWebScreenshotInputSchema, compareWebScreenshotsInputSchema, } from "./domain/webScreenshot.js";
@@ -69,7 +69,7 @@ const registerWebMcp = (cli, logger) => {
                 .describe("Maximum nesting depth in one declared tool schema"),
         }),
         run: ({ args, options }) => logCliCommand(logger, "discover-webmcp-tools", async () => {
-            const context = await browserContext();
+            const context = await browserContext("discover_webmcp_tools");
             if (!context.ok)
                 return context.error;
             const parsed = discoverWebMcpToolsInputSchema.safeParse({
@@ -155,7 +155,7 @@ const registerScreenshot = (cli, logger) => {
                 .describe("Maximum captured PNG size"),
         }),
         run: ({ args, options }) => logCliCommand(logger, "capture-web-screenshot", async () => {
-            const context = await browserContext();
+            const context = await browserContext("capture_web_screenshot");
             if (!context.ok)
                 return context.error;
             const parsed = captureWebScreenshotInputSchema.safeParse({
@@ -210,10 +210,16 @@ const registerScreenshotDiff = (cli, logger) => {
         }),
     });
 };
-const browserContext = async () => {
+const browserContext = async (operation) => {
     const config = parseConfig(process.env);
     if (!config.ok)
         return { ok: false, error: cliError(config.error) };
+    const policy = config.value.browserObservationPolicy;
+    if (policy.status === "disabled")
+        return {
+            ok: false,
+            error: cliError(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser observation is disabled; configure exact endpoints and origins before enabling it")),
+        };
     const authority = await loadConfiguredPermissionAuthority(config.value);
     if (!authority.ok)
         return { ok: false, error: cliError(authority.error) };
@@ -221,7 +227,7 @@ const browserContext = async () => {
         ok: true,
         authority: authority.value,
         provider: new CdpBrowserProvider(),
-        allowedBrowserOrigins: config.value.browserAllowedOrigins,
+        allowedBrowserOrigins: policy.allowedOrigins,
     };
 };
 const parseJson = (value) => {

package/dist/cliBrowserCommands.js

@@ -7,7 +7,7 @@ import { parseConfig } from "./config.js";
 import { inspectWebPageInputSchema, listBrowserTargetsInputSchema, } from "./domain/browserObservation.js";
 import { analyzeWebBundleInputSchema } from "./domain/webBundleAnalysis.js";
 import { observeWebSessionInputSchema } from "./domain/browserSession.js";
-import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+import { AnalysisCapabilityUnavailableError, AnalysisInputError, projectAnalysisError, } from "./domain/errors.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
 import { browserPageInspectionOptions } from "./cliObservationOptions.js";
 const browserScopeOptions = {
@@ -49,7 +49,7 @@ const registerTargetList = (cli, logger) => {
             limit: boundedCount("browser targets to return", 200, 100),
         }),
         run: ({ args, options }) => logCliCommand(logger, "list-browser-targets", async () => {
-            const context = await browserContext();
+            const context = await browserContext("list_browser_targets");
             if (!context.ok)
                 return context.error;
             const parsed = listBrowserTargetsInputSchema.safeParse({
@@ -75,7 +75,7 @@ const registerPageInspection = (cli, logger) => {
         }),
         options: browserPageInspectionOptions,
         run: ({ args, options }) => logCliCommand(logger, "inspect-web-page", async () => {
-            const context = await browserContext();
+            const context = await browserContext("inspect_web_page");
             if (!context.ok)
                 return context.error;
             const parsed = inspectWebPageInputSchema.safeParse({
@@ -92,6 +92,7 @@ const registerPageInspection = (cli, logger) => {
                 include_websocket_shapes: options.includeWebsocketShapes,
                 websocket_shape_approved: options.websocketShapeApproved,
                 include_script_sources: options.includeScriptSources,
+                source_capture_approved: options.sourceCaptureApproved,
                 include_storage_keys: options.includeStorageKeys,
                 include_storage_fingerprints: options.includeStorageFingerprints,
                 limits: {
@@ -157,7 +158,7 @@ const registerBundleAnalysis = (cli, logger) => {
             maxOriginalSources: boundedCount("original source files", 20_000, 2_000),
         }),
         run: ({ args, options }) => logCliCommand(logger, "analyze-web-bundle", async () => {
-            const context = await browserContext();
+            const context = await browserContext("analyze_web_bundle");
             if (!context.ok)
                 return context.error;
             const parsed = analyzeWebBundleInputSchema.safeParse({
@@ -200,7 +201,7 @@ const registerObservationSession = (cli, logger) => {
             maxTimelineEvents: boundedCount("timeline events", 20_000, 2_000),
         }),
         run: ({ args, options }) => logCliCommand(logger, "observe-web-session", async () => {
-            const context = await browserContext();
+            const context = await browserContext("observe_web_session");
             if (!context.ok)
                 return context.error;
             const parsed = observeWebSessionInputSchema.safeParse({
@@ -218,10 +219,16 @@ const registerObservationSession = (cli, logger) => {
         }),
     });
 };
-const browserContext = async () => {
+const browserContext = async (operation) => {
     const config = parseConfig(process.env);
     if (!config.ok)
         return { ok: false, error: cliError(config.error) };
+    const policy = config.value.browserObservationPolicy;
+    if (policy.status === "disabled")
+        return {
+            ok: false,
+            error: cliError(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser observation is disabled; configure exact endpoints and origins before enabling it")),
+        };
     const authority = await loadConfiguredPermissionAuthority(config.value);
     if (!authority.ok)
         return { ok: false, error: cliError(authority.error) };
@@ -229,7 +236,7 @@ const browserContext = async () => {
         ok: true,
         authority: authority.value,
         provider: new CdpBrowserProvider(),
-        allowedBrowserOrigins: config.value.browserAllowedOrigins,
+        allowedBrowserOrigins: policy.allowedOrigins,
     };
 };
 const cliError = (error) => ({

package/dist/cliCommandNames.js

@@ -12,6 +12,7 @@ export const CLI_COMMANDS = Object.freeze({
     capabilities: "capabilities",
     providers: "providers",
     function: "function",
+    inspectNativeApi: "inspect-native-api",
     instructions: "instructions",
     search: "search",
     importReferenceSource: "import-reference-source",
@@ -49,6 +50,7 @@ export const CLI_COMMANDS = Object.freeze({
     captureBrowserScenario: "capture-browser-scenario",
     listElectronTargets: "list-electron-targets",
     inspectElectronPage: "inspect-electron-page",
+    captureElectronScenario: "capture-electron-scenario",
     listJavaScriptRuntimeTargets: "list-javascript-runtime-targets",
     observeJavaScriptRuntime: "observe-javascript-runtime",
     analyzeJavaScriptApplication: "analyze-javascript-application",

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"),