rea-agents 6.1.0 → 6.2.0

package/dist/cli/omittableDefaults.js

@@ -0,0 +1,50 @@
+import { Cli, z } from "incur";
+const INPUT_GROUPS = ["args", "env", "options"];
+// Incur types its router key without vars, env, or globals; accept any CLI.
+const registeredCommands = Cli.toCommands;
+/**
+ * Advertise parser-filled defaults as omittable CLI inputs.
+ *
+ * Incur derives `--schema`, the `--llms` manifests, and help synopses from
+ * Zod's output view, where a defaulted field always has a value and is
+ * therefore listed as required. Callers may omit such a field, so each one is
+ * wrapped as optional while its default, constraints, metadata, and parsed
+ * value stay unchanged.
+ */
+export const presentOmittableDefaults = (cli) => {
+    const commands = registeredCommands.get(cli);
+    if (commands !== undefined)
+        presentCommands(commands);
+};
+const presentCommands = (commands) => {
+    for (const entry of commands.values()) {
+        if ("_group" in entry) {
+            presentCommands(entry.commands);
+            if (entry.root !== undefined)
+                presentInputs(entry.root);
+        }
+        else if (!("_alias" in entry) && !("_fetch" in entry))
+            presentInputs(entry);
+    }
+};
+const presentInputs = (command) => {
+    for (const group of INPUT_GROUPS) {
+        const schema = command[group];
+        if (schema instanceof z.ZodObject)
+            command[group] = withOmittableDefaults(schema);
+    }
+};
+const withOmittableDefaults = (schema) => {
+    const omittable = Object.entries(schema.shape).filter(([, field]) => fillsOmission(field));
+    if (omittable.length === 0)
+        return schema;
+    return schema.safeExtend(Object.fromEntries(omittable.map(([key, field]) => [key, optionalWithMetadata(field)])));
+};
+/** Zod accepts an omitted value (`optin`) but always produces one (`optout`). */
+const fillsOmission = (field) => field._zod.optin === "optional" && field._zod.optout === undefined;
+const optionalWithMetadata = (field) => {
+    const metadata = field.meta();
+    return metadata === undefined
+        ? field.optional()
+        : field.optional().meta(metadata);
+};

package/dist/cli/processCommands.js

@@ -2,12 +2,13 @@ import { Cli, z } from "incur";
 import { captureProcessScenarioFile, compareProcessEvidenceFiles, isProcessCliFailure, } from "../application/process/ProcessCli.js";
 import { logCliCommand } from "../cliLogging.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { withCommandCancellation } from "./commandCancellation.js";
 /** Register direct process capture and comparison commands. */
-export const registerProcessCommands = (cli, logger, environment = process.env) => {
+export const registerProcessCommands = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.captureProcess, {
         description: "Capture one caller-selected process scenario",
         args: z.object({ scenario: z.string().describe("Scenario JSON path") }),
-        run: ({ args }) => logCliCommand(logger, "capture-process", () => captureProcessScenarioFile(args.scenario, environment), isProcessCliFailure),
+        run: ({ args }) => withCommandCancellation((signal) => logCliCommand(logger, "capture-process", () => captureProcessScenarioFile(args.scenario, environment, signal), isProcessCliFailure)),
     });
     cli.command(CLI_COMMANDS.compareProcessCaptures, {
         description: "Compare two process capture Evidence JSON files",

package/dist/cli/setupCommands.js

@@ -3,7 +3,8 @@ import { DOCTOR_PROVIDER_IDS, runDoctor, } from "../application/Doctor.js";
 import { isSetupFailure, } from "../application/SetupTypes.js";
 import { runSetup } from "../application/Setup.js";
 import { systemSetupHost } from "../application/SetupHost.js";
-import { isUninstallFailure, runUninstall } from "../application/Uninstall.js";
+import { isUninstallFailure, runUninstall, systemUninstallHost, } from "../application/Uninstall.js";
+import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
 import { isUpdateFailure, runUpdate } from "../application/Update.js";
 import { systemUpdateHost } from "../application/UpdateRuntime.js";
 import { confirmInteractiveSetup, renderInteractiveSetupResult, renderSetupProgress, } from "./interactiveSetup.js";
@@ -17,12 +18,12 @@ const supportedClientSchema = z
     .string()
     .refine((candidate) => supportedClientIds.some((name) => name === candidate), "Unsupported agent integration");
 /** Register setup, doctor, uninstall, and update CLI commands. */
-export const registerSetupCommands = (cli, logger) => {
-    registerSetupCommand(cli, logger);
-    registerDoctorCommand(cli, logger);
-    registerMaintenanceCommands(cli, logger);
+export const registerSetupCommands = (cli, logger, environment) => {
+    registerSetupCommand(cli, logger, environment);
+    registerDoctorCommand(cli, logger, environment);
+    registerMaintenanceCommands(cli, logger, environment);
 };
-const registerSetupCommand = (cli, logger) => {
+const registerSetupCommand = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.setup, {
         description: "Configure agent integrations and optional analysis providers",
         outputPolicy: "agent-only",
@@ -57,10 +58,10 @@ const registerSetupCommand = (cli, logger) => {
                 .describe("Use sequential accessible setup prompts"),
         }),
         alias: { yes: "y" },
-        run: ({ options, formatExplicit }) => logCliCommand(logger, CLI_COMMANDS.setup, () => runSetupCommand({ options, formatExplicit }), isSetupFailure),
+        run: ({ options, formatExplicit }) => logCliCommand(logger, CLI_COMMANDS.setup, () => runSetupCommand({ options, formatExplicit }, environment), isSetupFailure),
     });
 };
-const registerDoctorCommand = (cli, logger) => {
+const registerDoctorCommand = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.doctor, {
         description: "Check whether REA is ready",
         options: z.object({
@@ -78,10 +79,10 @@ const registerDoctorCommand = (cli, logger) => {
                 .optional()
                 .describe("Require the installed REA skill identity to be aligned"),
         }),
-        run: ({ options }) => logCliCommand(logger, "doctor", () => runDoctor(options.target, createSystemDoctorHost(), doctorScope(options))),
+        run: ({ options }) => logCliCommand(logger, "doctor", () => runDoctor(options.target, createSystemDoctorHost(environment), doctorScope(options))),
     });
 };
-const registerMaintenanceCommands = (cli, logger) => {
+const registerMaintenanceCommands = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.uninstall, {
         description: "Remove REA-owned agent configuration and skill files",
         options: z.object({
@@ -91,22 +92,22 @@ const registerMaintenanceCommands = (cli, logger) => {
                 .describe("Also remove REA caches and state"),
         }),
         alias: { purgeData: "purge-data" },
-        run: ({ options }) => logCliCommand(logger, "uninstall", () => runUninstall(options.purgeData), isUninstallFailure),
+        run: ({ options }) => logCliCommand(logger, "uninstall", () => runUninstall(options.purgeData, systemUninstallHost(homeDirectoryFromEnvironment(environment, process.platform), undefined, environment)), isUninstallFailure),
     });
     cli.command(CLI_COMMANDS.update, {
         description: "Update this REA installation and verify the installed release",
-        run: ({ formatExplicit }) => logCliCommand(logger, CLI_COMMANDS.update, () => runUpdate(PRODUCT_IDENTITY.packageVersion, systemUpdateHost(), formatExplicit ? "structured" : "human"), isUpdateFailure),
+        run: ({ formatExplicit }) => logCliCommand(logger, CLI_COMMANDS.update, () => runUpdate(PRODUCT_IDENTITY.packageVersion, systemUpdateHost(undefined, undefined, environment), formatExplicit ? "structured" : "human"), isUpdateFailure),
     });
 };
-const runSetupCommand = async (input) => {
+const runSetupCommand = async (input, environment) => {
     const { options } = input;
     const interactive = setupIsInteractive(options, input.formatExplicit);
     const hasExplicitScope = setupHasExplicitScope(options);
-    const result = await runSetup(setupRunOptions(input, interactive, hasExplicitScope), systemSetupHost(createSystemDoctorHost()), interactive
+    const result = await runSetup(setupRunOptions(input, interactive, hasExplicitScope), systemSetupHost(createSystemDoctorHost(environment), environment), interactive
         ? (actions, context) => confirmInteractiveSetup(actions, options.accessible, context)
         : undefined);
     if (interactive)
-        renderInteractiveSetupResult(result);
+        renderInteractiveSetupResult(result, environment);
     return result;
 };
 const setupRunOptions = (input, interactive, hasExplicitScope) => {

package/dist/cli/utilityCommands.js

@@ -1,8 +1,7 @@
 import { z } from "incur";
-import { runCapabilityStatus, runProviderAnalysis, runProviderStatus, } from "../composition/directAnalysis.js";
 import { importReferenceSource } from "../application/ReferenceSourceImport.js";
 import { projectReferenceSourceImportError } from "../application/ReferenceSourceImportTypes.js";
-import { parseConfig } from "../config.js";
+import { parseConfig } from "../config/parseConfig.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 import { projectInputIssues } from "../domain/inputIssueProjection.js";
@@ -14,10 +13,11 @@ import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { swiftSymbolsSchema } from "../contracts/native/nativeToolContracts.js";
 import { isReferenceSourceImportCliFailure } from "./referenceSourceImportStatus.js";
 import { registerNativeCallCommands } from "./nativeCallCommands.js";
-export const registerUtilityCommands = (cli, logger, environment = process.env) => {
-    registerCapabilityCommands(cli, logger);
-    registerNativeCommands(cli, logger);
-    registerNativeCallCommands(cli, logger);
+export const registerUtilityCommands = (cli, logger, environment, analysis) => {
+    const { runProviderAnalysis } = analysis;
+    registerCapabilityCommands(cli, logger, analysis);
+    registerNativeCommands(cli, logger, runProviderAnalysis);
+    registerNativeCallCommands(cli, logger, runProviderAnalysis);
     for (const [command, operation] of [
         [CLI_COMMANDS.observeNativeUi, "observe_native_ui"],
         [CLI_COMMANDS.captureNativeUiScenario, "capture_native_ui_scenario"],
@@ -97,7 +97,7 @@ const invalidNativeUiScenarioInput = (operation, issues) => ({
     error: "Application workflow failed",
     ...projectAnalysisError(new AnalysisInputError(operation, undefined, issues)),
 });
-const registerCapabilityCommands = (cli, logger) => {
+const registerCapabilityCommands = (cli, logger, { runProviderStatus, runCapabilityStatus, }) => {
     for (const command of [
         CLI_COMMANDS.capabilities,
         CLI_COMMANDS.providers,
@@ -112,7 +112,7 @@ const registerCapabilityCommands = (cli, logger) => {
         });
     }
 };
-const registerNativeCommands = (cli, logger) => {
+const registerNativeCommands = (cli, logger, runProviderAnalysis) => {
     for (const [command, tool] of [
         [CLI_COMMANDS.inspectMacho, "inspect_macho"],
         [CLI_COMMANDS.inspectSignature, "inspect_signature"],
@@ -147,7 +147,7 @@ const registerNativeCommands = (cli, logger) => {
         run: ({ args }) => logCliCommand(logger, "demangle-swift", () => runProviderAnalysis(args.path, "demangle_swift", { symbols: args.symbols }, logger)),
     });
 };
-const registerReferenceSourceCommand = (cli, logger, environment = process.env) => {
+const registerReferenceSourceCommand = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.importReferenceSource, {
         description: "Import a source tree as historical reference only",
         args: z.object({

package/dist/cli.js

@@ -1,4 +1,7 @@
+import { snapshotEnvironment } from "./process/snapshotEnvironment.js";
+import { createDirectAnalysis } from "./composition/directAnalysis.js";
 import { registerEvmCommands } from "./cli/evmCommands.js";
+import { registerAnalysisViewCommands } from "./cli/analysisViewCommands.js";
 import { registerBinaryDiagnosticsCommands } from "./cli/binaryDiagnosticsCommands.js";
 import { Cli } from "incur";
 import { createLogger, parseLogLevel } from "./logger.js";
@@ -25,12 +28,15 @@ import { registerBrowserScenarioCommands } from "./cliBrowserScenarioCommands.js
 import { registerElectronCommands } from "./cli/electronCommands.js";
 import { registerJavaScriptRuntimeObservationCommands } from "./cliJavaScriptRuntimeCommands.js";
 import { registerApplicationCommands } from "./cli/applicationCommands.js";
+import { presentOmittableDefaults } from "./cli/omittableDefaults.js";
 /**
  * Build the one-shot Incur CLI without starting Hopper at import time.
  * Analysis commands acquire and close their own sessions; bare `mcp` and
  * `--mcp` are intercepted by the executable dispatcher before this module loads.
  */
-export const createCli = (environment = process.env, resultOutput) => {
+export const createCli = (selectedEnvironment = process.env, resultOutput) => {
+    const environment = snapshotEnvironment(selectedEnvironment);
+    const analysis = createDirectAnalysis(environment);
     const logger = createLogger("cli", environment.REA_LOG_LEVEL === undefined
         ? "silent"
         : parseLogLevel(environment.REA_LOG_LEVEL));
@@ -43,15 +49,16 @@ export const createCli = (environment = process.env, resultOutput) => {
         },
         sync: false,
     });
-    registerSetupCommands(cli, logger);
-    registerCoreAnalysisCommands(cli, logger, resultOutput);
-    registerUtilityCommands(cli, logger, environment);
+    registerSetupCommands(cli, logger, environment);
+    registerCoreAnalysisCommands(cli, logger, analysis.runDirectAnalysis, resultOutput);
+    registerUtilityCommands(cli, logger, environment, analysis);
     registerEvmCommands(cli, logger, environment);
-    registerArtifactCommands(cli, logger);
-    registerManagedCommands(cli, logger);
+    registerArtifactCommands(cli, logger, analysis.runProviderAnalysis);
+    registerManagedCommands(cli, logger, analysis.runProviderAnalysis);
     registerAndroidCommands(cli, logger, environment);
     registerFirmwareCommands(cli, logger, environment);
     registerBinaryDiagnosticsCommands(cli, logger, environment);
+    registerAnalysisViewCommands(cli, logger);
     registerEvidenceCommands(cli, logger);
     registerProcessCommands(cli, logger, environment);
     registerBrowserCommands(cli, logger);
@@ -62,9 +69,10 @@ export const createCli = (environment = process.env, resultOutput) => {
     registerWebNetworkCaptureCommands(cli, logger, environment);
     registerJavaScriptRecoveryCommands(cli, logger, environment);
     registerAdvancedBrowserCommands(cli, logger);
-    registerBrowserScenarioCommands(cli, logger);
-    registerElectronCommands(cli, logger, resultOutput);
+    registerBrowserScenarioCommands(cli, logger, environment);
+    registerElectronCommands(cli, logger, environment, resultOutput);
     registerJavaScriptRuntimeObservationCommands(cli, logger);
     registerApplicationCommands(cli, logger);
+    presentOmittableDefaults(cli);
     return cli;
 };

package/dist/cliBrowserScenarioCommands.js

@@ -11,7 +11,7 @@ import { projectInputIssues } from "./domain/inputIssueProjection.js";
 import { browserScenarioSchema } from "./domain/browserScenario.js";
 const OPERATION = "capture_browser_scenario";
 /** Register the one-shot controlled browser scenario command. */
-export const registerBrowserScenarioCommands = (cli, logger) => {
+export const registerBrowserScenarioCommands = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.captureBrowserScenario, {
         description: "Run one bounded Playwright browser scenario and return Evidence",
         args: z.object({
@@ -26,7 +26,7 @@ export const registerBrowserScenarioCommands = (cli, logger) => {
             const scenario = browserScenarioSchema.safeParse(resolveCliJsonPaths(input.value, [["browser", "executable_path"]]));
             if (!scenario.success)
                 return cliError(new AnalysisInputError(OPERATION, { cause: scenario.error }, projectInputIssues(scenario.error.issues, input.value)));
-            const result = await captureBrowserScenario(createBrowserScenarioProvider(), scenario.data);
+            const result = await captureBrowserScenario(createBrowserScenarioProvider(environment), scenario.data);
             return result.ok ? result.value : cliError(result.error);
         }),
     });

package/dist/cliCommandNames.js

@@ -41,6 +41,7 @@ export const CLI_COMMANDS = Object.freeze({
     inspectManagedArtifact: "inspect-managed-artifact",
     inspectRecordedCrash: "inspect-recorded-crash",
     inspectBinaryLayout: "inspect-binary-layout",
+    inspectAnalysisView: "inspect-analysis-view",
     inspectFirmwareRegions: "inspect-firmware-regions",
     extractFirmware: "extract-firmware",
     inspectAndroidPackage: "inspect-android-package",

package/dist/cliJsonInput.js

@@ -95,8 +95,22 @@ const jsonFileError = (path, operation, reason, cause) => ({
         error: "Application workflow failed",
         ...projectAnalysisError(new AnalysisInputError(operation, cause === undefined ? undefined : { cause }, reason === "invalid-json"
             ? [{ path: [], reason: "invalid_format", expected: "JSON" }]
-            : [])),
+            : [readFailureIssue(path, cause)])),
         ...(path === undefined ? {} : { input_path: path }),
         input_reason: reason,
     },
 });
+/** Name the system error so the caller can tell a typo from a permission denial. */
+const readFailureIssue = (path, cause) => {
+    const code = typeof cause === "object" &&
+        cause !== null &&
+        "code" in cause &&
+        typeof cause.code === "string"
+        ? ` (${cause.code})`
+        : "";
+    return {
+        path: [],
+        reason: "invalid_value",
+        message: `The JSON input file could not be read${code}: ${path ?? ""}`,
+    };
+};

package/dist/cliOutput.js

@@ -1,15 +1,5 @@
-import { safeParseJson } from "./domain/safeJson.js";
-const SAFE_VALIDATION_MESSAGE = "REA could not read the command arguments. Run `rea --help`, correct the arguments, then try again.";
 const UNSUPPORTED_OUTPUT_COMBINATION_MESSAGE = "Token windows cannot preserve structured output. Remove --token-limit/--token-offset and use --filter-output or command pagination.";
 const INCUR_OUTPUT_FORMATS = new Set(["toon", "json", "yaml", "md", "jsonl"]);
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const validationError = (value) => {
-    if (value.code === "VALIDATION_ERROR")
-        return value;
-    if (value.ok === false && isRecord(value.error))
-        return value.error.code === "VALIDATION_ERROR" ? value.error : undefined;
-    return undefined;
-};
 /** Read effective Incur output controls at the executable boundary. */
 export const parseCliOutputArguments = (arguments_) => {
     let format = "toon";
@@ -105,31 +95,3 @@ export const renderCliOutputArgumentError = (error) => {
         return `ok: false\nerror:\n  code: ${error.code}\n  message: ${JSON.stringify(error.message)}\n`;
     return `${JSON.stringify(value)}\n`;
 };
-/** Remove validator internals from Incur's caller-visible CLI output. */
-export const sanitizeCliOutput = (output) => {
-    const trimmed = output.trimStart();
-    if (trimmed.startsWith("{")) {
-        const decoded = safeParseJson(trimmed);
-        if (!decoded.ok)
-            return output;
-        const parsed = decoded.value;
-        if (!isRecord(parsed))
-            return output;
-        const error = validationError(parsed);
-        if (error !== undefined) {
-            const safeError = {
-                code: "VALIDATION_ERROR",
-                message: SAFE_VALIDATION_MESSAGE,
-            };
-            if (error === parsed)
-                return `${JSON.stringify(safeError)}\n`;
-            return `${JSON.stringify({ ...parsed, error: safeError })}\n`;
-        }
-        return output;
-    }
-    if (/^ok: false\r?\nerror:\r?\n  code: VALIDATION_ERROR(?:\r?\n|$)/u.test(trimmed))
-        return `ok: false\nerror:\n  code: VALIDATION_ERROR\n  message: "${SAFE_VALIDATION_MESSAGE}"\n`;
-    if (!/^code: VALIDATION_ERROR(?:\r?\n|$)/u.test(trimmed))
-        return output;
-    return `code: VALIDATION_ERROR\nmessage: "${SAFE_VALIDATION_MESSAGE}"\n`;
-};

package/dist/composition/auxiliaryAnalysisProviders.js

@@ -1,30 +1,34 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { ARTIFACT_PROVIDER_IDENTITY, artifactCapabilities, } from "../artifacts/ArtifactProviderMetadata.js";
 import { MANAGED_STATIC_PROVIDER_IDENTITY, managedStaticCapabilities, } from "../dotnet/ManagedStaticProviderMetadata.js";
 import { NATIVE_MACOS_PROVIDER_IDENTITY, nativeMacOSCapabilities, } from "../native/NativeMacOSProviderMetadata.js";
 /** Wire the three existing auxiliary AnalysisProvider implementations lazily. */
-export const auxiliaryAnalysisProviderDeclarations = (platform = process.platform) => [
-    {
-        identity: ARTIFACT_PROVIDER_IDENTITY,
-        capabilities: artifactCapabilities(platform),
-        load: async () => {
-            const { ArtifactProvider } = await import("../artifacts/ArtifactProvider.js");
-            return new ArtifactProvider(platform);
+export const auxiliaryAnalysisProviderDeclarations = (selectedEnvironment, platform = process.platform) => {
+    const environment = snapshotEnvironment(selectedEnvironment, platform);
+    return [
+        {
+            identity: ARTIFACT_PROVIDER_IDENTITY,
+            capabilities: artifactCapabilities(platform),
+            load: async () => {
+                const { ArtifactProvider } = await import("../artifacts/ArtifactProvider.js");
+                return new ArtifactProvider(environment, platform);
+            },
         },
-    },
-    {
-        identity: NATIVE_MACOS_PROVIDER_IDENTITY,
-        capabilities: nativeMacOSCapabilities(platform),
-        load: async () => {
-            const { NativeMacOSProvider } = await import("../native/NativeMacOSProvider.js");
-            return new NativeMacOSProvider(undefined, platform);
+        {
+            identity: NATIVE_MACOS_PROVIDER_IDENTITY,
+            capabilities: nativeMacOSCapabilities(platform),
+            load: async () => {
+                const { NativeMacOSProvider } = await import("../native/NativeMacOSProvider.js");
+                return new NativeMacOSProvider(environment, undefined, platform);
+            },
         },
-    },
-    {
-        identity: MANAGED_STATIC_PROVIDER_IDENTITY,
-        capabilities: managedStaticCapabilities(),
-        load: async () => {
-            const { ManagedStaticProvider } = await import("../dotnet/ManagedStaticProvider.js");
-            return new ManagedStaticProvider();
+        {
+            identity: MANAGED_STATIC_PROVIDER_IDENTITY,
+            capabilities: managedStaticCapabilities(),
+            load: async () => {
+                const { ManagedStaticProvider } = await import("../dotnet/ManagedStaticProvider.js");
+                return new ManagedStaticProvider();
+            },
         },
-    },
-];
+    ];
+};

package/dist/composition/binary.js

@@ -1,25 +1,25 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { HopperProvider } from "../hopper/HopperProvider.js";
 import { GhidraProvider } from "../ghidra/GhidraProvider.js";
 import { IdaProvider } from "../ida/IdaProvider.js";
-import { silentLogger } from "../logger.js";
 import { auxiliaryAnalysisProviderDeclarations } from "./auxiliaryAnalysisProviders.js";
 import { AnalysisProviderRegistry } from "../application/binary/AnalysisProviderRegistry.js";
 import { composeBinarySession } from "../application/binary/BinarySessionComposition.js";
 import { LazyAnalysisProvider } from "../application/binary/LazyAnalysisProvider.js";
 import { ManagedStaticProvider } from "../dotnet/ManagedStaticProvider.js";
-import { SessionProviderRouter } from "../application/binary/SessionProviderRouter.js";
 /**
  * Compose the target-switching runtime shared directly by CLI and MCP adapters.
  * This is the sole production wiring point, so both adapters share identical
  * provider selection, profile, lifecycle, and Evidence semantics.
  */
-export const createBinarySession = (config, logger = silentLogger) => {
-    const hopper = new HopperProvider(config, logger);
-    const ghidra = new GhidraProvider(config, logger);
-    const ida = new IdaProvider(config);
-    return composeBinarySession(new AnalysisProviderRegistry([hopper, ghidra, ida], config.analysisProvider), auxiliaryAnalysisProviderDeclarations().map((declaration) => new LazyAnalysisProvider(declaration)));
+export const createBinarySession = (config, logger, selectedEnvironment) => {
+    const environment = snapshotEnvironment(selectedEnvironment);
+    const hopper = new HopperProvider(config, logger, environment);
+    const ghidra = new GhidraProvider(config, logger, environment);
+    const ida = new IdaProvider(config, environment);
+    return composeBinarySession(new AnalysisProviderRegistry([hopper, ghidra, ida], config.analysisProvider), auxiliaryAnalysisProviderDeclarations(environment).map((declaration) => new LazyAnalysisProvider(declaration)));
 };
 /** Compose an execution-free managed session without native provider selection. */
-export const createManagedBinarySession = () => composeBinarySession(SessionProviderRouter.selectable(new AnalysisProviderRegistry([]), [
+export const createManagedBinarySession = () => composeBinarySession(new AnalysisProviderRegistry([]), [
     new ManagedStaticProvider(),
-]));
+]);

package/dist/composition/browserScenario.js

@@ -1,3 +1,4 @@
 import { PlaywrightBrowserScenarioProvider } from "../browser/PlaywrightBrowserScenarioProvider.js";
+import { PlaywrightScenarioSessionFactory } from "../browser/PlaywrightScenarioSession.js";
 /** Construct a fresh provider without opening a target or acquiring an engine. */
-export const createBrowserScenarioProvider = () => new PlaywrightBrowserScenarioProvider();
+export const createBrowserScenarioProvider = (environment) => new PlaywrightBrowserScenarioProvider(new PlaywrightScenarioSessionFactory(environment));

package/dist/composition/directAnalysis.js

@@ -1,17 +1,24 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
+import { parseConfig } from "../config/parseConfig.js";
 import { runDirectAnalysis as executeDirectAnalysis, runProviderAnalysis as executeProviderAnalysis, runManagedProviderExecution as executeManagedProvider, } from "../application/DirectAnalysis.js";
 import { runCapabilityStatus as executeCapabilityStatus, runProviderStatus as executeProviderStatus, } from "../application/DirectAnalysisStatus.js";
 import { createBinarySession, createManagedBinarySession } from "./binary.js";
-const dependencies = {
-    createBinarySession,
-    createManagedBinarySession,
+/** Bind one-shot analysis and status commands to one caller-selected environment. */
+export const createDirectAnalysis = (selectedEnvironment) => {
+    const environment = snapshotEnvironment(selectedEnvironment);
+    const dependencies = {
+        readConfiguration: () => parseConfig(environment),
+        createBinarySession: (config, logger) => createBinarySession(config, logger, environment),
+        createManagedBinarySession,
+    };
+    return {
+        runDirectAnalysis: executeDirectAnalysis.bind(undefined, dependencies),
+        runProviderAnalysis: executeProviderAnalysis.bind(undefined, dependencies),
+        runProviderStatus: executeProviderStatus.bind(undefined, dependencies),
+        runCapabilityStatus: executeCapabilityStatus.bind(undefined, dependencies),
+    };
 };
-/** Run one isolated binary operation through the production session factory. */
-export const runDirectAnalysis = executeDirectAnalysis.bind(undefined, dependencies);
-/** Run one isolated native, artifact or managed operation. */
-export const runProviderAnalysis = executeProviderAnalysis.bind(undefined, dependencies);
-/** Execute managed metadata without constructing native provider candidates. */
-export const runManagedProviderExecution = executeManagedProvider.bind(undefined, dependencies);
-/** Report production provider candidates without opening a target. */
-export const runProviderStatus = executeProviderStatus.bind(undefined, dependencies);
-/** Report production session operations without opening a target. */
-export const runCapabilityStatus = executeCapabilityStatus.bind(undefined, dependencies);
+/** Execute managed metadata without configuration or native provider candidates. */
+export const runManagedProviderExecution = executeManagedProvider.bind(undefined, {
+    createManagedBinarySession,
+});

package/dist/composition/electronScenario.js

@@ -1,3 +1,3 @@
 import { PlaywrightElectronActiveProvider } from "../browser/PlaywrightElectronActiveProvider.js";
 /** Construct a fresh provider without opening a target or acquiring an engine. */
-export const createElectronScenarioProvider = () => new PlaywrightElectronActiveProvider();
+export const createElectronScenarioProvider = (environment) => new PlaywrightElectronActiveProvider(environment);

package/dist/composition/optionalObservationProviders.js

@@ -1,12 +1,17 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { CDP_BROWSER_PROVIDER_IDENTITY, PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY, CDP_ELECTRON_PROVIDER_IDENTITY, PLAYWRIGHT_ELECTRON_ACTIVE_PROVIDER_IDENTITY, } from "../browser/providerIdentities.js";
 import { V8_INSPECTOR_PROVIDER_IDENTITY } from "../inspector/providerIdentity.js";
 import { err, ok } from "../domain/result.js";
-const productionFactories = {
-    browserObservation: async () => (await import("./browserObservation.js")).createBrowserObservationProvider(),
-    browserScenarioCapture: async () => (await import("./browserScenario.js")).createBrowserScenarioProvider(),
-    electronObservation: async () => (await import("./electronObservation.js")).createElectronObservationProvider(),
-    electronActiveObservation: async () => (await import("./electronScenario.js")).createElectronScenarioProvider(),
-    javascriptRuntimeObservation: async () => (await import("./javascriptRuntimeObservation.js")).createJavaScriptRuntimeObservationProvider(),
+/** Bind optional provider construction to one caller-selected process environment. */
+export const createOptionalObservationFactories = (selectedEnvironment) => {
+    const environment = snapshotEnvironment(selectedEnvironment);
+    return {
+        browserObservation: async () => (await import("./browserObservation.js")).createBrowserObservationProvider(),
+        browserScenarioCapture: async () => (await import("./browserScenario.js")).createBrowserScenarioProvider(environment),
+        electronObservation: async () => (await import("./electronObservation.js")).createElectronObservationProvider(),
+        electronActiveObservation: async () => (await import("./electronScenario.js")).createElectronScenarioProvider(environment),
+        javascriptRuntimeObservation: async () => (await import("./javascriptRuntimeObservation.js")).createJavaScriptRuntimeObservationProvider(),
+    };
 };
 const loadPort = async (factory, providerId) => {
     try {
@@ -20,7 +25,7 @@ const loadPort = async (factory, providerId) => {
     }
 };
 /** Load each adapter independently, retaining healthy peers and exact failures. */
-export const loadOptionalObservationProviders = async (factories = productionFactories) => {
+export const loadOptionalObservationProviders = async (factories) => {
     const [browser, scenario, electron, electronActive, runtime] = await Promise.all([
         loadPort(factories.browserObservation, CDP_BROWSER_PROVIDER_IDENTITY.id),
         loadPort(factories.browserScenarioCapture, PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id),

package/dist/config/environment.js

@@ -46,8 +46,14 @@ const environmentSchema = z.object({
 export const parseEnvironment = (environment) => {
     const parsed = environmentSchema.safeParse(environment);
     if (!parsed.success) {
+        // Zod messages name the constraint, never the rejected value.
+        const settings = parsed.error.issues.map((issue) => ({
+            setting: String(issue.path[0] ?? "environment"),
+            constraint: issue.message,
+        }));
         return err(new ConfigurationError("Invalid REA environment configuration", {
             cause: parsed.error,
+            settings,
         }));
     }
     return ok(parsed.data);

package/dist/config/ghidraStartupTimeout.js

@@ -6,12 +6,7 @@ const MAX_TIMER_DELAY_MS = 2_147_483_647;
 /** Parse the optional setting without reading the ambient process environment. */
 export const ghidraStartupTimeoutSchema = z
     .string()
-    .optional()
-    .transform((raw) => {
-    const value = Number(raw);
-    return Number.isSafeInteger(value) &&
-        value > 0 &&
-        value <= MAX_TIMER_DELAY_MS
-        ? value
-        : DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS;
-});
+    .regex(/^[1-9]\d*$/u, "must be a positive decimal integer")
+    .transform(Number)
+    .pipe(z.number().int().min(1).max(MAX_TIMER_DELAY_MS))
+    .default(DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS);

package/dist/config/homeDirectory.js

@@ -0,0 +1,12 @@
+import { userInfo } from "node:os";
+/** Resolve the caller's selected home before consulting the host account. */
+export const homeDirectoryFromEnvironment = (environment, platform) => {
+    const selected = platform === "win32"
+        ? (environment.USERPROFILE ??
+            (environment.HOMEDRIVE !== undefined &&
+                environment.HOMEPATH !== undefined
+                ? `${environment.HOMEDRIVE}${environment.HOMEPATH}`
+                : environment.HOME))
+        : (environment.HOME ?? environment.USERPROFILE);
+    return selected ?? userInfo().homedir;
+};

package/dist/config/mcpResponseBudget.js

@@ -11,6 +11,7 @@ export const mcpResponseBudgetSchema = z
     .regex(/^[1-9]\d*$/u)
     .transform(Number)
     .pipe(z.number().int().safe().min(MINIMUM_RESPONSE_BYTES));
+const budgetConstraint = `REA_MCP_MAX_RESPONSE_BYTES must be a decimal safe integer at least ${String(MINIMUM_RESPONSE_BYTES)} bytes, the default stdio receive-buffer size.`;
 /** Parse only the MCP-specific budget without loading unrelated provider settings. */
 export const parseMcpResponseBudget = (value) => {
     if (value === undefined)
@@ -18,5 +19,12 @@ export const parseMcpResponseBudget = (value) => {
     const parsed = mcpResponseBudgetSchema.safeParse(value);
     return parsed.success
         ? ok(parsed.data)
-        : err(new ConfigurationError(`REA_MCP_MAX_RESPONSE_BYTES must be a decimal safe integer at least ${String(MINIMUM_RESPONSE_BYTES)} bytes, the default stdio receive-buffer size.`));
+        : err(new ConfigurationError(budgetConstraint, {
+            settings: [
+                {
+                    setting: "REA_MCP_MAX_RESPONSE_BYTES",
+                    constraint: budgetConstraint,
+                },
+            ],
+        }));
 };