rea-agents 6.0.0 → 6.2.0

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",
@@ -139,7 +140,6 @@ export const MCP_TOOLS_WITHOUT_DEDICATED_CLI = Object.freeze([
     "set_addresses_names",
     "set_bookmark",
     "set_comment",
-    "set_current_document",
     "set_inline_comment",
     "unset_bookmark",
     "get_objc_classes",

package/dist/cliJsonInput.js

@@ -27,9 +27,9 @@ export const parseCliJsonInput = async (value, operation) => {
 /**
  * Resolve named string fields of CLI-supplied JSON against the operator
  * working directory. Each entry is a key path from the document root; only
- * fields holding strings are resolved, everything else passes through
- * untouched. Shared MCP contracts reject relative paths, so CLI workflows
- * resolve operator-relative values before validation.
+ * fields holding nonblank strings are resolved, everything else passes through
+ * untouched so shared schemas can reject blank paths. Shared MCP contracts reject
+ * relative paths, so CLI workflows resolve operator-relative values before validation.
  */
 export const resolveCliJsonPaths = (value, paths) => {
     let resolved = value;
@@ -45,7 +45,12 @@ const resolveJsonPath = (value, keys) => {
         if (key !== head)
             return [key, entry];
         if (tail.length === 0)
-            return [key, typeof entry === "string" ? resolve(entry) : entry];
+            return [
+                key,
+                typeof entry === "string" && entry.trim().length > 0
+                    ? resolve(entry)
+                    : entry,
+            ];
         return [key, resolveJsonPath(entry, tail)];
     });
     return Object.fromEntries(entries);
@@ -90,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

@@ -3,8 +3,11 @@ import { isAbsolute } from "node:path";
 import { ConfigurationError } from "../domain/configurationErrors.js";
 import { err, ok } from "../domain/result.js";
 import { analysisProviderSelectorSchema } from "../contracts/providerSelection.js";
+import { ghidraStartupTimeoutSchema } from "./ghidraStartupTimeout.js";
+import { mcpResponseBudgetSchema } from "./mcpResponseBudget.js";
 const environmentSchema = z.object({
     REA_ANALYSIS_PROVIDER: analysisProviderSelectorSchema.default("auto"),
+    REA_MCP_MAX_RESPONSE_BYTES: mcpResponseBudgetSchema.optional(),
     REA_IDA_MCP_CONFIG: z
         .string()
         .min(1)
@@ -25,6 +28,7 @@ const environmentSchema = z.object({
         .min(1)
         .refine(isAbsolute, "REA_GHIDRA_NATIVEAOT_JAR must be absolute")
         .optional(),
+    REA_GHIDRA_STARTUP_TIMEOUT_MS: ghidraStartupTimeoutSchema,
     REA_ILSPY_CMD_PATH: z
         .string()
         .min(1)
@@ -42,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

@@ -0,0 +1,12 @@
+import { z } from "zod";
+/** Default absolute deadline for Ghidra import, analysis, bridge, and readiness. */
+export const DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS = 330_000;
+// Node schedules delays above this signed 32-bit boundary as a 1 ms timer.
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** Parse the optional setting without reading the ambient process environment. */
+export const ghidraStartupTimeoutSchema = z
+    .string()
+    .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

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { ConfigurationError } from "../domain/configurationErrors.js";
+import { err, ok } from "../domain/result.js";
+// This override supports clients with larger frames. Keep the configuration
+// parser independent of the SDK's eager server imports; conformance verifies
+// this floor against the pinned SDK's actual default receive-buffer size.
+const MINIMUM_RESPONSE_BYTES = 10 * 1024 * 1024;
+/** Optional stdio response budget, including room for the protocol envelope. */
+export const mcpResponseBudgetSchema = z
+    .string()
+    .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)
+        return ok(undefined);
+    const parsed = mcpResponseBudgetSchema.safeParse(value);
+    return parsed.success
+        ? ok(parsed.data)
+        : 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;
     }
 };
-export 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,17 +37,22 @@ 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
             ? {}
             : { idaMcpConfigPath: env.REA_IDA_MCP_CONFIG }),
         ghidraInstallDir: env.GHIDRA_INSTALL_DIR,
         ghidraJavaHome: env.JAVA_HOME,
+        ghidraStartupTimeoutMs: env.REA_GHIDRA_STARTUP_TIMEOUT_MS,
         ...(env.REA_GHIDRA_NATIVEAOT_JAR === undefined
             ? {}
             : { 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,
             },
             {

package/dist/contracts/artifactComparisonExample.js

@@ -8,13 +8,11 @@ const inventory = (digit) => {
     const nodes = [
         {
             artifact_id: artifactId,
-            kind: "resource",
             format: "file",
             sha256: sha,
             size: 1,
             media_type: null,
             architecture: null,
-            executable: false,
             content_state: "materialized",
             limitations: [],
         },
@@ -26,6 +24,8 @@ const inventory = (digit) => {
             parent_occurrence_id: null,
             logical_path: ".",
             entry_kind: "file",
+            artifact_kind: "resource",
+            artifact_format: "file",
             declared_size: 1,
             compressed_size: null,
             executable: false,

package/dist/contracts/artifactToolContracts.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { artifactOutputSchemas } from "./toolOutputSchemas.js";
+import { artifactOutputSchemas } from "./toolOutputSchemaGroups.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { toolContractMetadata } from "./toolEffects.js";
 import { requireOutputSchema } from "./toolOutputSchemaPrimitives.js";