rea-agents 6.1.0 → 6.2.0

package/dist/browser/PlaywrightScenarioSession.js

@@ -1,11 +1,12 @@
 import {} from "playwright-core";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { BrowserScenarioSecrets } from "./BrowserScenarioSecrets.js";
-import { closePlaywrightScenarioBrowser, openPlaywrightScenarioBrowser, } from "./PlaywrightScenarioBrowser.js";
+import { failBrowserScenarioOperation, openPlaywrightScenarioBrowser, } from "./PlaywrightScenarioBrowser.js";
 import { performPlaywrightScenarioAction } from "./PlaywrightScenarioActions.js";
 import { capturePlaywrightStepArtifacts } from "./PlaywrightScenarioArtifacts.js";
 import { PlaywrightScenarioEvents } from "./PlaywrightScenarioEvents.js";
 import { withPlaywrightExecutionBoundary } from "./PlaywrightExecutionBoundary.js";
+import { browserScenarioCaptureData, browserScenarioOperationFailure, } from "./BrowserScenarioPartialObservation.js";
 const OPERATION = "capture_browser_scenario";
 const storageSeeds = (blocks, secrets) => {
     const seeds = {};
@@ -66,10 +67,8 @@ export class PlaywrightScenarioSession {
     product = "Chromium";
     version;
     initialUrl;
-    closed = false;
     secrets;
     eventCapture;
-    signal;
     constructor(opened, options) {
         this.opened = opened;
         this.mode = options.mode;
@@ -77,7 +76,6 @@ export class PlaywrightScenarioSession {
             options.mode === "launch" ? "provider-owned" : "external";
         this.secrets = options.secrets;
         this.eventCapture = options.eventCapture;
-        this.signal = options.signal;
         this.version = opened.browser.version();
         this.initialUrl = opened.page.url();
     }
@@ -87,23 +85,26 @@ export class PlaywrightScenarioSession {
         const secrets = BrowserScenarioSecrets.resolve(scenario, environment);
         if (secrets === undefined)
             throw new BrowserObservationError(OPERATION, "secret_unavailable");
+        const startedAt = Date.now();
         const opening = openPlaywrightScenarioBrowser(scenario, environment);
         let opened;
+        let events;
         try {
             opened = await withPlaywrightExecutionBoundary(() => opening, undefined, options.signal);
         }
         catch (cause) {
             void opening
-                .then((lateOpened) => closePlaywrightScenarioBrowser(lateOpened, options.signal))
+                .then((lateOpened) => lateOpened.cleanup.close(undefined, options.signal))
                 .catch((cause) => {
                 // best-effort cleanup: late-open cleanup must not mask the boundary failure.
                 void cause;
             });
             throw cause;
         }
+        let session;
         try {
             await withPlaywrightExecutionBoundary(() => initializePage(opened.context, opened.page, scenario, secrets), undefined, options.signal);
-            const events = new PlaywrightScenarioEvents({
+            events = new PlaywrightScenarioEvents({
                 page: opened.page,
                 context: opened.context,
                 ownsContext: scenario.browser.mode === "launch",
@@ -112,12 +113,18 @@ export class PlaywrightScenarioSession {
                 network: scenario.capture.network,
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
-            const session = new PlaywrightScenarioSession(opened, {
+            session = new PlaywrightScenarioSession(opened, {
                 mode: scenario.browser.mode,
                 secrets,
                 eventCapture: events,
-                ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
+        }
+        catch (cause) {
+            return failBrowserScenarioOperation(() => opened.cleanup.close(events === undefined
+                ? undefined
+                : () => events?.finish() ?? Promise.resolve(), options.signal), cause);
+        }
+        try {
             await withPlaywrightExecutionBoundary(() => opened.page.goto(secrets.url(scenario.start_url), {
                 waitUntil: "load",
                 timeout: 0,
@@ -125,8 +132,28 @@ export class PlaywrightScenarioSession {
             return session;
         }
         catch (cause) {
-            await closePlaywrightScenarioBrowser(opened, options.signal);
-            throw cause;
+            let cleanup;
+            let cleanupFailure;
+            try {
+                cleanup = await session.close();
+            }
+            catch (failure) {
+                cleanup = "incomplete";
+                cleanupFailure = { cause: failure };
+            }
+            throw browserScenarioOperationFailure(cause, {
+                kind: "browser-scenario-observation",
+                capture: browserScenarioCaptureData({
+                    session,
+                    scenario,
+                    startedAt,
+                    steps: [],
+                    cleanup,
+                    limitations: [
+                        "Scenario navigation failed before the initial state was captured.",
+                    ],
+                }),
+            }, cleanupFailure);
         }
     }
     currentUrl() {
@@ -167,17 +194,7 @@ export class PlaywrightScenarioSession {
         }), undefined, signal);
     }
     async close() {
-        if (this.closed)
-            return this.mode === "launch"
-                ? "terminated-owned-process"
-                : "disconnected-external";
-        this.closed = true;
-        try {
-            await this.eventCapture.finish();
-        }
-        finally {
-            await closePlaywrightScenarioBrowser(this.opened, this.signal);
-        }
+        await this.opened.cleanup.close(() => this.eventCapture.finish());
         return this.mode === "launch"
             ? "terminated-owned-process"
             : "disconnected-external";
@@ -189,7 +206,7 @@ export class PlaywrightScenarioSession {
 /** Production Playwright/CDP session factory. */
 export class PlaywrightScenarioSessionFactory {
     environment;
-    constructor(environment = process.env) {
+    constructor(environment) {
         this.environment = environment;
     }
     open(scenario, options = {}) {

package/dist/browser/assets/ScriptCaptureAdapters.js

@@ -1,4 +1,4 @@
-import { webPageInspectionSchema } from "../../domain/browserObservation.js";
+import { webPageInspectionSchema } from "../../domain/browserObservationSchemas.js";
 import { browserScenarioCaptureSchema } from "../../domain/browserScenarioCapture.js";
 import { parseEvidence } from "../../domain/evidence.js";
 import { pageScripts } from "./PageScriptCapture.js";

package/dist/browser/history/CaptureFailures.js

@@ -34,7 +34,8 @@ export const historicalCaptureFailure = (input, cause, phase, options) => {
         if (phase === "decoder" &&
             input.format === "har" &&
             cause.reason === "process" &&
-            cause.snapshot?.signal === "SIGABRT" &&
+            (cause.snapshot?.signal === "SIGABRT" ||
+                (cause.snapshot?.signal === null && cause.snapshot.exitCode === 134)) &&
             /FATAL ERROR:[^\r\n]*heap out of memory/u.test(cause.snapshot.stderr.text))
             return captureMemoryFailure(input, "The HAR decoder exhausted its fixed V8 heap", cause);
     }
@@ -120,7 +121,10 @@ export const captureMemoryFailure = (input, reason, cause) => new AnalysisResour
         }
         : {}),
     ...(cause instanceof OwnedCommandFailure
-        ? { observed_signal: cause.snapshot?.signal ?? null }
+        ? {
+            observed_exit_code: cause.snapshot?.exitCode ?? null,
+            observed_signal: cause.snapshot?.signal ?? null,
+        }
         : {}),
 }, {
     cause,

package/dist/browser/history/MitmproxyCaptureAdapter.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
 import { MITMPROXY_CAPTURE_PROVIDER_IDENTITY } from "./CaptureRelease.js";
 const OPERATION = "inspect_web_network_capture";
+const MITMDUMP_REQUIREMENT = "Native capture decoding requires Linux and an absolute REA_MITMDUMP_COMMAND path to caller-supplied mitmdump 12.2.3; HAR needs no external engine.";
 /** Native mitmproxy decoding is offline and uses only an explicitly configured Linux tool. */
 export class MitmproxyCaptureAdapter {
     environment;
@@ -18,12 +19,13 @@ export class MitmproxyCaptureAdapter {
         if (process.platform !== "linux" ||
             command === undefined ||
             !isAbsolute(command))
-            throw new AnalysisCapabilityUnavailableError("mitmproxy", OPERATION, "Native capture decoding requires Linux and an absolute REA_MITMDUMP_COMMAND path to caller-supplied mitmdump 12.2.3; HAR needs no external engine.");
+            throw new AnalysisCapabilityUnavailableError("mitmproxy", OPERATION, MITMDUMP_REQUIREMENT, { userMessage: MITMDUMP_REQUIREMENT });
         try {
             await access(command, constants.R_OK | constants.X_OK);
         }
         catch (cause) {
-            throw new AnalysisCapabilityUnavailableError("mitmproxy", OPERATION, `Configured mitmdump executable is unavailable: ${command}.`, { cause });
+            const reason = `Configured mitmdump executable is unavailable: ${command}.`;
+            throw new AnalysisCapabilityUnavailableError("mitmproxy", OPERATION, reason, { cause, userMessage: reason });
         }
         return {
             command,

package/dist/catalogIdentity.js

@@ -4,7 +4,6 @@ import { z } from "zod";
 import { PROMPT_CONTRACTS } from "./contracts/promptContracts.js";
 import { TOOL_CONTRACTS } from "./contracts/toolContracts.js";
 import { CLI_COMMAND_NAMES } from "./cliCommandNames.js";
-export { CLI_COMMAND_NAMES } from "./cliCommandNames.js";
 const sortedToolContracts = [...TOOL_CONTRACTS].sort((left, right) => left.name.localeCompare(right.name));
 const createToolCatalog = () => sortedToolContracts.map((contract) => ({
     name: contract.name,

package/dist/cli/analysisViewCommands.js

@@ -0,0 +1,36 @@
+import { z } from "incur";
+import { inspectAnalysisViewValidated } from "../application/analysisView/AnalysisViewService.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { parseCliJsonInput } from "../cliJsonInput.js";
+import { logCliCommand } from "../cliLogging.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { inspectAnalysisViewInputSchema } from "../domain/analysisView/analysisView.js";
+/** Project selected views of completed analysis Evidence through the CLI. */
+export const registerAnalysisViewCommands = (cli, logger) => {
+    cli.command(CLI_COMMANDS.inspectAnalysisView, {
+        description: "Project a selected view of completed layout or JavaScript application Evidence JSON",
+        args: z.object({
+            inputJson: z.string().describe("Inline workflow JSON or JSON file path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.inspectAnalysisView, async () => {
+            const input = await parseCliJsonInput(args.inputJson, CLI_COMMANDS.inspectAnalysisView);
+            if (!input.ok)
+                return input.error;
+            const parsed = inspectAnalysisViewInputSchema.safeParse(input.value);
+            if (!parsed.success)
+                return {
+                    error: "Application workflow failed",
+                    ...projectAnalysisError(analysisInputErrorFromIssues(CLI_COMMANDS.inspectAnalysisView, parsed.error.issues, input.value)),
+                };
+            const result = inspectAnalysisViewValidated(parsed.data);
+            return result.ok
+                ? jsonValueSchema.parse(result.value)
+                : {
+                    error: "Application workflow failed",
+                    ...projectAnalysisError(result.error),
+                };
+        }),
+    });
+};

package/dist/cli/artifactCommands.js

@@ -1,14 +1,13 @@
 import { z } from "incur";
-import { runProviderAnalysis } from "../composition/directAnalysis.js";
 import { createArtifactExtractionDestination } from "../application/artifacts/ArtifactExtractionDestination.js";
 import { logCliCommand } from "../cliLogging.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
-export const registerArtifactCommands = (cli, logger) => {
-    registerInspectionCommand(cli, logger);
-    registerExtractionCommand(cli, logger);
-    registerInterfaceBuilderCommand(cli, logger);
-    registerAssetCatalogCommand(cli, logger);
-    registerDylibResolutionCommand(cli, logger);
+export const registerArtifactCommands = (cli, logger, runProviderAnalysis) => {
+    registerInspectionCommand(cli, logger, runProviderAnalysis);
+    registerExtractionCommand(cli, logger, runProviderAnalysis);
+    registerInterfaceBuilderCommand(cli, logger, runProviderAnalysis);
+    registerAssetCatalogCommand(cli, logger, runProviderAnalysis);
+    registerDylibResolutionCommand(cli, logger, runProviderAnalysis);
     cli.command(CLI_COMMANDS.inspectKeyedArchive, {
         description: "Inspect a Foundation keyed archive as an object-reference graph",
         args: z.object({
@@ -42,7 +41,7 @@ export const registerArtifactCommands = (cli, logger) => {
         }, logger)),
     });
 };
-const registerDylibResolutionCommand = (cli, logger) => {
+const registerDylibResolutionCommand = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.traceDylibResolution, {
         description: "Trace dyld load-path resolution for a Mach-O or every executable in an app bundle",
         args: z.object({
@@ -66,7 +65,7 @@ const registerDylibResolutionCommand = (cli, logger) => {
         }, logger)),
     });
 };
-const registerAssetCatalogCommand = (cli, logger) => {
+const registerAssetCatalogCommand = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.inspectAssetCatalog, {
         description: "Inspect compiled Apple asset catalog metadata",
         args: z.object({ path: z.string().describe("Apple .app bundle path") }),
@@ -89,7 +88,7 @@ const registerAssetCatalogCommand = (cli, logger) => {
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.inspectAssetCatalog, () => runProviderAnalysis(args.path, "inspect_asset_catalog", { offset: options.offset, limit: options.limit }, logger)),
     });
 };
-const registerInterfaceBuilderCommand = (cli, logger) => {
+const registerInterfaceBuilderCommand = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.decodeInterfaceBuilder, {
         description: "Decode compiled storyboard and nib archives from an app bundle",
         args: z.object({
@@ -130,7 +129,7 @@ const registerInterfaceBuilderCommand = (cli, logger) => {
         }, logger)),
     });
 };
-const registerExtractionCommand = (cli, logger) => {
+const registerExtractionCommand = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.extractArtifact, {
         description: "Extract all regular artifact contents safely",
         args: z.object({
@@ -142,7 +141,7 @@ const registerExtractionCommand = (cli, logger) => {
         }, logger)),
     });
 };
-const registerInspectionCommand = (cli, logger) => {
+const registerInspectionCommand = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.inspectArtifact, {
         description: "Inspect one artifact and return all available observations and next probes",
         args: z.object({

package/dist/cli/coreAnalysisCommands.js

@@ -1,7 +1,7 @@
 import { registerCoreBinaryCommands } from "./coreBinaryCommands.js";
 import { registerCoreNativeCommands } from "./coreNativeCommands.js";
 /** Register core binary and native deep-analysis CLI commands. */
-export const registerCoreAnalysisCommands = (cli, logger, resultOutput) => {
-    registerCoreBinaryCommands(cli, logger, resultOutput);
-    registerCoreNativeCommands(cli, logger);
+export const registerCoreAnalysisCommands = (cli, logger, runDirectAnalysis, resultOutput) => {
+    registerCoreBinaryCommands(cli, logger, runDirectAnalysis, resultOutput);
+    registerCoreNativeCommands(cli, logger, runDirectAnalysis);
 };

package/dist/cli/coreBinaryCommands.js

@@ -2,22 +2,22 @@ import { z } from "incur";
 import { stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { resolveCliAnalysisSelector } from "./analysisSelector.js";
-import { runDirectAnalysis } from "../composition/directAnalysis.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { logCliCommand } from "../cliLogging.js";
 import { directAnalysisOptions, formatSelectionOption, providerSelectionOption, } from "./options.js";
 import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
+import { withCommandCancellation } from "./commandCancellation.js";
 /** Register provider-neutral binary overview and procedure CLI commands. */
-export const registerCoreBinaryCommands = (cli, logger, resultOutput) => {
-    registerOverviewCommands(cli, logger, resultOutput);
-    registerDecompileCommand(cli, logger);
-    registerFunctionCommand(cli, logger);
-    registerInstructionsCommand(cli, logger);
-    registerSearchCommand(cli, logger);
-    registerXrefsCommand(cli, logger);
-    registerTraceCommand(cli, logger);
+export const registerCoreBinaryCommands = (cli, logger, runDirectAnalysis, resultOutput) => {
+    registerOverviewCommands(cli, logger, runDirectAnalysis, resultOutput);
+    registerDecompileCommand(cli, logger, runDirectAnalysis);
+    registerFunctionCommand(cli, logger, runDirectAnalysis);
+    registerInstructionsCommand(cli, logger, runDirectAnalysis);
+    registerSearchCommand(cli, logger, runDirectAnalysis);
+    registerXrefsCommand(cli, logger, runDirectAnalysis);
+    registerTraceCommand(cli, logger, runDirectAnalysis);
 };
-const registerOverviewCommands = (cli, logger, resultOutput) => {
+const registerOverviewCommands = (cli, logger, runDirectAnalysis, resultOutput) => {
     const overviewOptions = z.object({
         snapshot: z
             .string()
@@ -33,9 +33,17 @@ const registerOverviewCommands = (cli, logger, resultOutput) => {
             path: z.string().describe("App, program, or analysis database path"),
         }),
         options: overviewOptions,
-        run: ({ args, options, format }) => logCliCommand(logger, "analyze", () => runRoutedOverview(args.path, options, logger, resultOutput === undefined
-            ? undefined
-            : { output: resultOutput, command: CLI_COMMANDS.analyze, format })),
+        run: async ({ args, options, format }) => {
+            const output = resultOutput === undefined
+                ? undefined
+                : { output: resultOutput, command: CLI_COMMANDS.analyze, format };
+            // Route JavaScript targets exactly like analyze-javascript-application,
+            // including typed cancellation; cancellation wraps logging so its exit
+            // code is not replaced by the logged failure status.
+            if (await routesToJavaScriptAnalysis(args.path, options))
+                return withCommandCancellation((signal) => logCliCommand(logger, "analyze", () => runCliJavaScriptApplicationAnalysis({ input_path: resolve(args.path) }, output, signal)));
+            return logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", {}, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"])));
+        },
     });
     cli.command(CLI_COMMANDS.inspect, {
         description: "Inspect an app overview with evidence",
@@ -46,7 +54,7 @@ const registerOverviewCommands = (cli, logger, resultOutput) => {
         run: ({ args, options }) => logCliCommand(logger, "inspect", () => runDirectAnalysis(args.path, "binary_overview", {}, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const registerDecompileCommand = (cli, logger) => {
+const registerDecompileCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.decompile, {
         description: "Read one part of an app as code",
         args: z.object({
@@ -76,14 +84,11 @@ const registerDecompileCommand = (cli, logger) => {
         }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const runRoutedOverview = async (path, options, logger, output) => {
-    if (options.provider === undefined &&
-        options.snapshot === undefined &&
-        options["target-format"] === undefined &&
-        (await isJavaScriptApplicationPath(path)))
-        return runCliJavaScriptApplicationAnalysis({ input_path: resolve(path) }, output);
-    return runDirectAnalysis(path, "binary_overview", {}, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]));
-};
+/** Select static JavaScript analysis only when no binary-analysis option applies. */
+const routesToJavaScriptAnalysis = async (path, options) => options.provider === undefined &&
+    options.snapshot === undefined &&
+    options["target-format"] === undefined &&
+    (await isJavaScriptApplicationPath(path));
 const isJavaScriptApplicationPath = async (path) => {
     const lower = path.toLowerCase();
     if (lower.endsWith(".asar"))
@@ -100,7 +105,7 @@ const isJavaScriptApplicationPath = async (path) => {
         return false;
     }
 };
-const registerXrefsCommand = (cli, logger) => {
+const registerXrefsCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.xrefs, {
         description: "List bounded references to an analyzed address",
         args: z.object({
@@ -126,7 +131,7 @@ const registerXrefsCommand = (cli, logger) => {
         }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const registerTraceCommand = (cli, logger) => {
+const registerTraceCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.trace, {
         description: "Trace a literal feature through analyzed references",
         args: z.object({
@@ -160,7 +165,7 @@ const registerTraceCommand = (cli, logger) => {
         }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const registerFunctionCommand = (cli, logger) => {
+const registerFunctionCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.function, {
         description: "Analyze one complete function with evidence",
         args: z.object({
@@ -190,7 +195,7 @@ const registerFunctionCommand = (cli, logger) => {
         }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const registerInstructionsCommand = (cli, logger) => {
+const registerInstructionsCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.instructions, {
         description: "Read every raw instruction without decompiling",
         args: z.object({
@@ -220,7 +225,7 @@ const registerInstructionsCommand = (cli, logger) => {
         }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const registerSearchCommand = (cli, logger) => {
+const registerSearchCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.search, {
         description: "Search every analyzed string or procedure name",
         args: z.object({

package/dist/cli/coreNativeCommands.js

@@ -1,11 +1,10 @@
 import { z } from "incur";
-import { runDirectAnalysis } from "../composition/directAnalysis.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { logCliCommand } from "../cliLogging.js";
 import { directAnalysisOptions, formatSelectionOption, providerSelectionOption, } from "./options.js";
 /** Register native load-image, memory, and annotation CLI commands. */
-export const registerCoreNativeCommands = (cli, logger) => {
-    registerAnnotationCommand(cli, logger);
+export const registerCoreNativeCommands = (cli, logger, runDirectAnalysis) => {
+    registerAnnotationCommand(cli, logger, runDirectAnalysis);
     cli.command(CLI_COMMANDS.inspectNativeLoadImage, {
         description: "Verify loaded native bytes, source mappings, relocations and entry",
         args: z.object({ path: z.string().describe("Local executable path") }),
@@ -160,11 +159,11 @@ export const registerCoreNativeCommands = (cli, logger) => {
             run: ({ args, options }) => logCliCommand(logger, command, () => runDirectAnalysis(args.path, operation, { address: args.address }, directAnalysisOptions(logger, undefined, options.provider, options["target-format"]))),
         });
     }
-    registerNativeApiCommand(cli, logger);
-    registerNativeUiActionCommand(cli, logger);
-    registerNativeDispatchMetadataCommand(cli, logger);
+    registerNativeApiCommand(cli, logger, runDirectAnalysis);
+    registerNativeUiActionCommand(cli, logger, runDirectAnalysis);
+    registerNativeDispatchMetadataCommand(cli, logger, runDirectAnalysis);
 };
-const registerNativeDispatchMetadataCommand = (cli, logger) => {
+const registerNativeDispatchMetadataCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.inspectNativeDispatchMetadata, {
         description: "Inspect typed Objective-C and Swift dispatch metadata",
         args: z.object({
@@ -190,7 +189,7 @@ const registerNativeDispatchMetadataCommand = (cli, logger) => {
         run: async ({ args, options }) => logCliCommand(logger, "inspect-native-dispatch-metadata", () => runDirectAnalysis(args.path, "inspect_native_dispatch_metadata", { max_records: options.maxRecords }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const registerNativeUiActionCommand = (cli, logger) => {
+const registerNativeUiActionCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.traceNativeUiAction, {
         description: "Trace a compiled UI action selector to its native handler and direct callees",
         args: z.object({
@@ -238,7 +237,7 @@ const registerNativeUiActionCommand = (cli, logger) => {
         }, directAnalysisOptions(logger, undefined, options.provider, options["target-format"]))),
     });
 };
-const registerNativeApiCommand = (cli, logger) => {
+const registerNativeApiCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.inspectNativeApi, {
         description: "Reconstruct one native function API boundary with evidence",
         args: z.object({
@@ -257,7 +256,7 @@ const registerNativeApiCommand = (cli, logger) => {
         run: ({ args, options }) => logCliCommand(logger, "inspect-native-api", () => runDirectAnalysis(args.path, "inspect_native_api", { procedure: args.address }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const registerAnnotationCommand = (cli, logger) => {
+const registerAnnotationCommand = (cli, logger, runDirectAnalysis) => {
     cli.command(CLI_COMMANDS.annotateNativeFunction, {
         description: "Edit function annotations and return refreshed analysis",
         args: z.object({

package/dist/cli/electronCommands.js

@@ -14,13 +14,13 @@ import { electronPageInspectionOptions, javascriptApplicationOptions, } from "..
 import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
 import { withCommandCancellation } from "./commandCancellation.js";
 /** Register CLI equivalents of the Electron MCP tools. */
-export const registerElectronCommands = (cli, logger, resultOutput) => {
+export const registerElectronCommands = (cli, logger, environment, resultOutput) => {
     registerElectronObservationCommands(cli, logger);
-    registerElectronActiveCommand(cli, logger);
+    registerElectronActiveCommand(cli, logger, environment);
     registerJavaScriptApplicationCommand(cli, logger, resultOutput);
     registerJavaScriptRuntimeReconciliationCommand(cli, logger);
 };
-const registerElectronActiveCommand = (cli, logger) => {
+const registerElectronActiveCommand = (cli, logger, environment) => {
     cli.command(CLI_COMMANDS.captureElectronScenario, {
         description: "Run one owned Electron scenario with cancellable actions",
         args: z.object({
@@ -40,7 +40,7 @@ const registerElectronActiveCommand = (cli, logger) => {
             if (!parsed.success)
                 return inputError("capture_electron_scenario", parsed.error.issues, input.value);
             const { createElectronScenarioProvider } = await import("../composition/electronScenario.js");
-            const result = await captureElectronScenario(createElectronScenarioProvider(), parsed.data, { signal });
+            const result = await captureElectronScenario(createElectronScenarioProvider(environment), parsed.data, { signal });
             return result.ok ? result.value : cliError(result.error);
         })),
     });

package/dist/cli/interactiveSetup.js

@@ -53,13 +53,13 @@ export const renderSetupProgress = (event) => {
     writeLine(`${symbol}  ${event.label}${suffix}`);
 };
 /** Finish an interactive setup journey without exposing the full doctor catalog. */
-export const renderInteractiveSetupResult = (result) => {
+export const renderInteractiveSetupResult = (result, environment = process.env) => {
     if (result.status === "ready") {
         const changedClients = Object.entries(result.clients)
             .filter(([, client]) => client.status === "configured")
             .map(([client]) => clientDisplayNames.get(client) ?? client);
         const readyClients = readyAgentClients(result, changedClients);
-        renderReadyCapabilities(result, readyClients);
+        renderReadyCapabilities(result, readyClients, environment);
         outro(changedClients.length === 0
             ? "REA is ready for local app analysis."
             : `Restart ${changedClients.join(", ")} to load REA.`, promptStreams);
@@ -68,7 +68,7 @@ export const renderInteractiveSetupResult = (result) => {
     if (result.status === "planned" || result.status === "cancelled")
         return;
     writeLine(`!  ${result.remediation ?? "Setup needs attention."}`);
-    outro(`Run \`${cliInvocation()} doctor\` for the remaining checks.`, promptStreams);
+    outro(`Run \`${cliInvocation(environment)} doctor\` for the remaining checks.`, promptStreams);
 };
 const selectSetupActions = async (actions, accessible, context) => {
     const clientStates = context.clientStates.filter(({ client }) => client.format !== "unsupported");
@@ -167,8 +167,8 @@ const renderKeyboardHelp = (accessible) => {
         ? "│  Keys: Enter answer · Ctrl-C cancel"
         : "│  Keys: ↑/↓ navigate · Space toggle · Enter confirm · Ctrl-C cancel");
 };
-const cliInvocation = () => process.env.npm_command === "exec" ? "npx rea-agents" : "rea";
-const renderReadyCapabilities = (result, readyClients) => {
+const cliInvocation = (environment) => environment.npm_command === "exec" ? "npx rea-agents" : "rea";
+const renderReadyCapabilities = (result, readyClients, environment) => {
     writeLine("◆  What you can do now");
     const providers = readyProviders(result);
     if (providers.length > 0)
@@ -177,7 +177,7 @@ const renderReadyCapabilities = (result, readyClients) => {
         writeLine(`│  Agent access: ${humanList(readyClients)}`);
     if (result.doctor.identity?.skill.state === "aligned")
         writeLine("│  Guided reverse-engineering workflows: installed");
-    writeLine(`│  CLI: ${cliInvocation()} ${providers.length > 0 ? "analyze /path/to/app" : "capabilities"}`);
+    writeLine(`│  CLI: ${cliInvocation(environment)} ${providers.length > 0 ? "analyze /path/to/app" : "capabilities"}`);
     const firstClient = readyClients[0];
     if (firstClient !== undefined)
         writeLine(`│  Try in ${firstClient}: "Explain how a feature works in /path/to/app and show the evidence."`);

package/dist/cli/managedCommands.js

@@ -2,22 +2,21 @@ import { z } from "incur";
 import { compareManagedMemberPaths } from "../application/managed/ManagedMemberComparisonService.js";
 import { verifyManagedNativeBoundariesEvidence } from "../application/managed/ManagedNativeVerificationService.js";
 import { importManagedReconstructionEvidence } from "../application/managed/ManagedReconstructionService.js";
-import { runProviderAnalysis } from "../composition/directAnalysis.js";
 import { parseCliJsonInput } from "../cliJsonInput.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { logCliCommand } from "../cliLogging.js";
 import { registerProjectManagedApplicationGraph } from "./managedProjectGraphCommand.js";
-export const registerManagedCommands = (cli, logger) => {
-    registerInspectManagedArtifact(cli, logger);
-    registerInspectManagedMembers(cli, logger);
-    registerInspectManagedNativeBoundaries(cli, logger);
+export const registerManagedCommands = (cli, logger, runProviderAnalysis) => {
+    registerInspectManagedArtifact(cli, logger, runProviderAnalysis);
+    registerInspectManagedMembers(cli, logger, runProviderAnalysis);
+    registerInspectManagedNativeBoundaries(cli, logger, runProviderAnalysis);
     registerCompareManagedMembers(cli, logger);
     registerImportManagedReconstruction(cli, logger);
     registerVerifyManagedNativeBoundaries(cli, logger);
     registerProjectManagedApplicationGraph(cli, logger);
 };
-const registerInspectManagedArtifact = (cli, logger) => {
+const registerInspectManagedArtifact = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.inspectManagedArtifact, {
         description: "Inspect PE/CLI identity without loading target code",
         args: z.object({
@@ -26,7 +25,7 @@ const registerInspectManagedArtifact = (cli, logger) => {
         run: ({ args }) => logCliCommand(logger, "inspect-managed-artifact", () => runProviderAnalysis(args.path, "inspect_managed_artifact", {}, logger)),
     });
 };
-const registerInspectManagedMembers = (cli, logger) => {
+const registerInspectManagedMembers = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.inspectManagedMembers, {
         description: "Inspect PE/CLI metadata members, signatures, and CIL anchors without loading target code",
         args: z.object({
@@ -35,7 +34,7 @@ const registerInspectManagedMembers = (cli, logger) => {
         run: ({ args }) => logCliCommand(logger, "inspect-managed-members", () => runProviderAnalysis(args.path, "inspect_managed_members", {}, logger)),
     });
 };
-const registerInspectManagedNativeBoundaries = (cli, logger) => {
+const registerInspectManagedNativeBoundaries = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.inspectManagedNativeBoundaries, {
         description: "Inspect PE/CLI PInvoke and native implementation boundary declarations without loading target code",
         args: z.object({

package/dist/cli/nativeCallCommands.js

@@ -1,5 +1,4 @@
 import { z } from "incur";
-import { runProviderAnalysis } from "../composition/directAnalysis.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { parseCliJsonInput } from "../cliJsonInput.js";
 import { logCliCommand } from "../cliLogging.js";
@@ -9,7 +8,7 @@ import { jsonValueSchema } from "../domain/jsonValue.js";
 import { nativeCallObservationInputSchema } from "../domain/native/nativeCallObservation.js";
 const OPERATION = "observe_native_calls";
 /** `observe-native-calls <path> <input-json>`: the MCP input object as JSON. */
-export const registerNativeCallCommands = (cli, logger) => {
+export const registerNativeCallCommands = (cli, logger, runProviderAnalysis) => {
     cli.command(CLI_COMMANDS.observeNativeCalls, {
         description: "Launch a Mach-O under LLDB and record entries into selected functions or Objective-C methods",
         args: z.object({