rea-agents 6.1.0 → 6.3.0

package/dist/cliJsonInput.js

@@ -1,29 +1,52 @@
-import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { AnalysisInputError } from "./domain/analysisErrorCore.js";
+import { readCliJsonFile } from "./cliJsonFile.js";
+import { NonRegularFileReadError } from "./filesystem/RegularFile.js";
+import { AnalysisAccessDeniedError, AnalysisInputError, } from "./domain/analysisErrorCore.js";
 import { projectAnalysisError } from "./domain/analysisErrorProjection.js";
 import { safeParseJson } from "./domain/safeJson.js";
 /** Parse inline JSON or one local JSON file for a CLI workflow. */
 export const parseCliJsonInput = async (value, operation) => {
-    const inline = parseJson(value);
-    if (inline !== undefined)
-        return { ok: true, value: inline };
+    const inline = safeParseJson(value);
+    if (inline.ok)
+        return { ok: true, value: inline.value };
     try {
-        // Read raw bytes so invalid UTF-8 is rejected by parseJson instead of
-        // being silently replaced by lossy "utf8" decoding.
-        const parsed = parseJson(await readFile(value));
-        return parsed === undefined
-            ? jsonFileError(value, operation, "invalid-json")
-            : { ok: true, value: parsed };
+        const parsed = await readCliJsonFile(value, operation);
+        return parsed.ok
+            ? { ok: true, value: parsed.value }
+            : {
+                ok: false,
+                error: {
+                    error: "Application workflow failed",
+                    ...projectAnalysisError(parsed.error),
+                    input_path: value,
+                    input_reason: parsed.error._tag === "AnalysisInputError"
+                        ? "invalid-json"
+                        : "too-large",
+                },
+            };
     }
     catch (cause) {
+        const systemCode = accessDeniedSystemCode(cause);
+        if (systemCode !== undefined)
+            return jsonAccessDeniedError(value, operation, systemCode, cause);
         if (["{", "["].includes(value.trimStart()[0] ?? "") &&
             cannotBeAnExistingFile(cause) &&
             !hasExplicitJsonFileExtension(value))
             return { ok: false, error: inputError(operation) };
+        if (!(cause instanceof Error) ||
+            !("code" in cause) ||
+            typeof cause.code !== "string")
+            throw cause;
         return jsonFileError(value, operation, "read-failed", cause);
     }
 };
+const accessDeniedSystemCode = (cause) => {
+    if (!(cause instanceof Error) || !("code" in cause))
+        return undefined;
+    return cause.code === "EACCES" || cause.code === "EPERM"
+        ? cause.code
+        : undefined;
+};
 /**
  * Resolve named string fields of CLI-supplied JSON against the operator
  * working directory. Each entry is a key path from the document root; only
@@ -62,27 +85,6 @@ const cannotBeAnExistingFile = (cause) => typeof cause === "object" &&
         cause.code === "ENAMETOOLONG" ||
         cause.code === "ENOTDIR");
 const hasExplicitJsonFileExtension = (value) => value.toLowerCase().endsWith(".json");
-const parseJson = (value) => {
-    let text;
-    if (typeof value === "string") {
-        text = value;
-    }
-    else {
-        try {
-            text = new TextDecoder("utf-8", {
-                fatal: true,
-                ignoreBOM: true,
-            }).decode(value);
-        }
-        catch (cause) {
-            // Decoding failure means the bytes are not valid UTF-8 JSON input.
-            void cause;
-            return undefined;
-        }
-    }
-    const parsed = safeParseJson(text);
-    return parsed.ok ? parsed.value : undefined;
-};
 const inputError = (operation) => ({
     error: "Application workflow failed",
     ...projectAnalysisError(new AnalysisInputError(operation, undefined, [
@@ -95,8 +97,33 @@ 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,
     },
 });
+const jsonAccessDeniedError = (path, operation, systemCode, cause) => ({
+    ok: false,
+    error: {
+        error: "Application workflow failed",
+        ...projectAnalysisError(new AnalysisAccessDeniedError(operation, path, systemCode, { cause })),
+        input_path: path,
+        input_reason: "read-failed",
+    },
+});
+/** Preserve file-selection and system failures alongside the requested path. */
+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: cause instanceof NonRegularFileReadError && cause.code === "ENOTFILE"
+            ? `The JSON input must be a regular file${code}: ${path ?? ""}`
+            : `The JSON input file could not be read${code}: ${path ?? ""}`,
+    };
+};

package/dist/cliObservationOptions.js

@@ -57,4 +57,8 @@ export const javascriptApplicationOptions = z.object({
         .enum(["auto", "asar", "directory"])
         .default("auto")
         .describe("Application artifact format"),
+    integrityPolicy: z
+        .enum(["fail", "record-and-continue"])
+        .default("fail")
+        .describe("Behavior when declared application integrity does not match"),
 });

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,35 @@
-import { ARTIFACT_PROVIDER_IDENTITY, artifactCapabilities, } from "../artifacts/ArtifactProviderMetadata.js";
-import { MANAGED_STATIC_PROVIDER_IDENTITY, managedStaticCapabilities, } from "../dotnet/ManagedStaticProviderMetadata.js";
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
+import { artifactCapabilities } from "../artifacts/ArtifactProviderMetadata.js";
+import { ARTIFACT_GRAPH_PROVIDER, MANAGED_STATIC_PROVIDER, } from "../application/InvestigationProviders.js";
+import { 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_GRAPH_PROVIDER,
+            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,
+            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 { PlaywrightScenarioSession } 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((scenario, options) => PlaywrightScenarioSession.open(scenario, environment, options));

package/dist/composition/directAnalysis.js

@@ -1,17 +1,23 @@
+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 { runSessionStatus as executeSessionStatus } 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),
+        runSessionStatus: executeSessionStatus.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,
+                },
+            ],
+        }));
 };

package/dist/config/parseConfig.js

@@ -1,9 +1,9 @@
 import { accessSync, constants } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { ConfigurationError } from "../domain/configurationErrors.js";
 import { ok } from "../domain/result.js";
 import { parseEnvironment } from "./environment.js";
+import { homeDirectoryFromEnvironment } from "./homeDirectory.js";
 import { parseStringArray, parseLoaderArgs } from "./parsers.js";
 const DEFAULT_HOPPER_LAUNCHER_PATH = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
 const SYSTEM_LINUX_HOPPER = "/opt/hopper/bin/Hopper";
@@ -16,7 +16,7 @@ const executableAvailable = (path) => {
         return false;
     }
 };
-const defaultHopperLauncherPath = (platform = process.platform, homeDirectory = homedir(), executable = executableAvailable) => {
+const defaultHopperLauncherPath = (platform, homeDirectory, executable = executableAvailable) => {
     if (platform !== "linux")
         return DEFAULT_HOPPER_LAUNCHER_PATH;
     if (executable(SYSTEM_LINUX_HOPPER))
@@ -37,6 +37,9 @@ export const parseConfig = (environment) => {
     if (!secretPatterns.ok)
         return secretPatterns;
     return ok({
+        ...(env.REA_MCP_MAX_RESPONSE_BYTES === undefined
+            ? {}
+            : { mcpMaxResponseBytes: env.REA_MCP_MAX_RESPONSE_BYTES }),
         analysisProvider: env.REA_ANALYSIS_PROVIDER,
         ...(env.REA_IDA_MCP_CONFIG === undefined
             ? {}
@@ -48,7 +51,8 @@ export const parseConfig = (environment) => {
             ? {}
             : { ghidraNativeAotJar: env.REA_GHIDRA_NATIVEAOT_JAR }),
         ilspyCmdPath: env.REA_ILSPY_CMD_PATH,
-        hopperLauncherPath: env.HOPPER_LAUNCHER_PATH ?? defaultHopperLauncherPath(),
+        hopperLauncherPath: env.HOPPER_LAUNCHER_PATH ??
+            defaultHopperLauncherPath(process.platform, homeDirectoryFromEnvironment(environment, process.platform)),
         hopperTargetPath: env.HOPPER_TARGET_PATH,
         hopperTargetKind: env.HOPPER_TARGET_KIND,
         hopperLoaderArgs: loaderArgs.value,

package/dist/config/parsers.js

@@ -1,33 +1,30 @@
 import { z } from "zod";
 import { ConfigurationError } from "../domain/configurationErrors.js";
 import { err, ok } from "../domain/result.js";
+import { safeParseJson } from "../domain/safeJson.js";
+/** Decode explicitly selected reference-source exclusion patterns. */
 export const parseStringArray = (encoded, name) => {
-    try {
-        const parsed = z.array(z.string().min(1)).safeParse(JSON.parse(encoded));
-        return parsed.success
-            ? ok(parsed.data)
-            : err(new ConfigurationError(`${name} must encode an array of strings`, {
-                cause: parsed.error,
-            }));
-    }
-    catch (cause) {
-        return err(new ConfigurationError(`${name} must be valid JSON`, { cause }));
-    }
+    return parseConfiguredStringArray(encoded, name, z.string().min(1));
 };
+/** Decode Hopper arguments while preserving meaningful empty argv entries. */
 export const parseLoaderArgs = (encoded) => {
     if (encoded === undefined)
         return ok([]);
-    let decoded;
-    try {
-        decoded = JSON.parse(encoded);
-    }
-    catch (cause) {
-        return err(new ConfigurationError("HOPPER_LOADER_ARGS_JSON must be valid JSON", {
-            cause,
-        }));
-    }
-    const parsed = z.array(z.string()).safeParse(decoded);
+    return parseConfiguredStringArray(encoded, "HOPPER_LOADER_ARGS_JSON", z.string());
+};
+const parseConfiguredStringArray = (encoded, setting, itemSchema) => {
+    const decoded = safeParseJson(encoded);
+    if (!decoded.ok)
+        return err(configuredArrayError(setting, "must be valid JSON", decoded.cause));
+    const parsed = z.array(itemSchema).safeParse(decoded.value);
     return parsed.success
         ? ok(parsed.data)
-        : err(new ConfigurationError("HOPPER_LOADER_ARGS_JSON must encode an array of strings", { cause: parsed.error }));
+        : err(configuredArrayError(setting, "must encode an array of strings", parsed.error));
+};
+const configuredArrayError = (setting, requirement, cause) => {
+    const constraint = `${setting} ${requirement}`;
+    return new ConfigurationError(constraint, {
+        cause,
+        settings: [{ setting, constraint }],
+    });
 };

package/dist/contracts/analysisViewToolContracts.js

@@ -0,0 +1,56 @@
+import { analysisViewResultSchema, inspectAnalysisViewInputSchema, } from "../domain/analysisView/analysisView.js";
+import { toolContractMetadata } from "./toolEffects.js";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
+const RETAINED_EXAMPLE_ID = `ev_${"a".repeat(64)}`;
+/** Selected views of already completed layout and JavaScript analysis Evidence. */
+export const ANALYSIS_VIEW_TOOL_CONTRACTS = [
+    {
+        name: "inspect_analysis_view",
+        ...toolContractMetadata("inspect_analysis_view"),
+        kind: "application",
+        description: "Inspect a selected view of completed binary-layout or JavaScript application Evidence without repeating analysis. Use an exact same-session retained evidence_id or portable inline Evidence. Select a summary, layout mitigations/linkage facet, one section/symbol/module, or a stable page with a positive limit. Module pages contain JavaScript assets, bundled modules and source modules; use node_id when paths are ambiguous or unavailable. Returns selected facts inline with artifact identity, parent Evidence ID, a distinct view digest, coverage, limitations and unknowns. Actual serialized size determines MCP transport admission; choose a smaller page or export the retained Evidence when needed.",
+        inputSchema: inspectAnalysisViewInputSchema,
+        outputSchema: evidenceResultOf(analysisViewResultSchema),
+        examples: [
+            {
+                title: "Summarize retained JavaScript application Evidence",
+                input: {
+                    source: {
+                        kind: "retained-evidence",
+                        evidence_id: RETAINED_EXAMPLE_ID,
+                    },
+                    view: { kind: "summary" },
+                },
+            },
+            {
+                title: "Read one ELF section from retained layout Evidence",
+                input: {
+                    source: {
+                        kind: "retained-evidence",
+                        evidence_id: RETAINED_EXAMPLE_ID,
+                    },
+                    view: {
+                        kind: "item",
+                        collection: "sections",
+                        selector: { name: ".text" },
+                    },
+                },
+            },
+            {
+                title: "Page module identities from retained application Evidence",
+                input: {
+                    source: {
+                        kind: "retained-evidence",
+                        evidence_id: RETAINED_EXAMPLE_ID,
+                    },
+                    view: {
+                        kind: "page",
+                        collection: "modules",
+                        offset: 0,
+                        limit: 32,
+                    },
+                },
+            },
+        ],
+    },
+];

package/dist/contracts/applicationToolContracts.js

@@ -10,8 +10,9 @@ import { reconstructionObligationLedgerInputSchema, reconstructionObligationLedg
 import { androidApplicationProjectionInputSchema, androidApplicationProjectionResultSchema, } from "../domain/android/androidApplication.js";
 import { appleApplicationProjectionInputSchema, appleApplicationProjectionResultSchema, } from "../domain/apple/appleApplication.js";
 import { toolContractMetadata } from "./toolEffects.js";
-import { evidenceResultOf } from "./toolOutputSchemas.js";
-import { JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE, JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE, JAVASCRIPT_FEATURE_TRACE_EXAMPLE, SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE, } from "./javascript/javascriptApplicationWorkflowExamples.js";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
+import { JAVASCRIPT_APPLICATION_VERSION_COMPARISON_EXAMPLE, JAVASCRIPT_FEATURE_TRACE_EXAMPLE, SOURCE_TO_BUNDLE_COMPARISON_EXAMPLE, } from "./javascript/javascriptApplicationWorkflowExamples.js";
+import { JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE } from "./javascript/javascriptExportShapeComparisonExample.js";
 import { ANDROID_APPLICATION_GRAPH_EXAMPLE, APPLE_APPLICATION_GRAPH_EXAMPLE, MACOS_APPLICATION_GRAPH_EXAMPLE, } from "./mobileApplicationGraphExamples.js";
 const traceOutputSchema = evidenceResultOf(applicationFeatureTraceResultSchema);
 const semanticTraceOutputSchema = evidenceResultOf(javaScriptSemanticTraceResultSchema);
@@ -106,13 +107,13 @@ export const APPLICATION_TOOL_CONTRACTS = [
     {
         name: "compare_javascript_export_shapes",
         ...toolContractMetadata("compare_javascript_export_shapes"),
-        description: "Compare static return shapes for one exact module/export selector on each authenticated JavaScript Application Graph supplied as inline Evidence or exact same-session retained references. Variants pair only by reciprocal unique literal discriminants; dynamic values, incomplete properties, and ambiguous variants remain unknown. Reports JSON Pointer changes without executing JavaScript; runtime behavior requires a separate agent-run probe.",
+        description: "Compare static return shapes for one exact module/export selector on each authenticated JavaScript Application Graph supplied as inline Evidence or exact same-session retained references. Variants pair only by reciprocal unique literal discriminants. Each retained variant lists observed return-property names even when values stay unknown. Presence (present, absent, or unknown-coverage) is separate from value resolution: a name present on only one paired shape is added or removed when parent-property coverage is complete on both sides, including when the static value is unresolved. Dynamic values, incomplete parent coverage, and unpaired variants remain unknown. Reports JSON Pointer changes without executing JavaScript; runtime behavior requires a separate agent-run probe.",
         kind: "application",
         inputSchema: compareJavaScriptExportShapesRequestSchema,
         outputSchema: exportShapeComparisonOutputSchema,
         examples: [
             {
-                title: "Compare one exact parser export without execution",
+                title: "Report observed return-property presence when static values stay unknown",
                 input: JAVASCRIPT_EXPORT_SHAPE_COMPARISON_EXAMPLE,
             },
             {