rea-agents 3.2.0 → 4.0.0

package/dist/cliCommandNames.js

@@ -6,7 +6,7 @@ export const CLI_COMMANDS = Object.freeze({
     setup: "setup",
     doctor: "doctor",
     uninstall: "uninstall",
-    upgrade: "upgrade",
+    update: "update",
     xrefs: "xrefs",
     trace: "trace",
     traceNativeUiAction: "trace-native-ui-action",
@@ -21,14 +21,21 @@ export const CLI_COMMANDS = Object.freeze({
     inspectArtifact: "inspect-artifact",
     extractArtifact: "extract-artifact",
     decodeInterfaceBuilder: "decode-interface-builder",
+    inspectKeyedArchive: "inspect-keyed-archive",
+    inspectNativeDataType: "inspect-native-data-type",
+    traceNativeValues: "trace-native-values",
+    inspectNativeInstruction: "inspect-native-instruction",
+    resolveNativeCallTargets: "resolve-native-call-targets",
+    inspectAssetCatalog: "inspect-asset-catalog",
     inspectManagedArtifact: "inspect-managed-artifact",
     inspectManagedMembers: "inspect-managed-members",
     inspectManagedNativeBoundaries: "inspect-managed-native-boundaries",
     compareManagedMembers: "compare-managed-members",
     verifyManagedNativeBoundaries: "verify-managed-native-boundaries",
     importManagedReconstruction: "import-managed-reconstruction",
-    planManagedRuntimeCorrelation: "plan-managed-runtime-correlation",
     projectManagedApplicationGraph: "project-managed-application-graph",
+    observeNativeUi: "observe-native-ui",
+    captureNativeUiScenario: "capture-native-ui-scenario",
     inspectMacho: "inspect-macho",
     inspectSignature: "inspect-signature",
     listArchitectures: "list-architectures",
@@ -39,7 +46,6 @@ export const CLI_COMMANDS = Object.freeze({
     compare: "compare",
     captureProcess: "capture-process",
     compareProcessCaptures: "compare-process-captures",
-    policy: "policy",
     listBrowserTargets: "list-browser-targets",
     inspectWebPage: "inspect-web-page",
     analyzeWebBundle: "analyze-web-bundle",
@@ -61,12 +67,81 @@ export const CLI_COMMANDS = Object.freeze({
     compareApplicationVersions: "compare-application-versions",
     compareSourceToBundle: "compare-source-to-bundle",
     compareJavaScriptExportShapes: "compare-javascript-export-shapes",
-    runReplayMachine: "run-replay-machine",
-    runControlledReplay: "run-controlled-replay",
-    prepareNodeCharacterization: "prepare-node-characterization",
-    executeNodeCharacterization: "execute-node-characterization",
     buildReconstructionObligationLedger: "build-reconstruction-obligation-ledger",
     evaluateReconstructionCoverage: "evaluate-reconstruction-coverage",
 });
 /** Ordered primary CLI inventory; aliases are intentionally excluded. */
 export const CLI_COMMAND_NAMES = Object.freeze(Object.values(CLI_COMMANDS));
+/** Command aliases registered on top of the primary CLI command inventory. */
+export const CLI_COMMAND_ALIASES = Object.freeze(["compare-bundles"]);
+/** Canonical MCP operations reached by CLI commands with different names. */
+export const CLI_COMMAND_TOOL_ALIASES = Object.freeze({
+    analyze: ["binary_overview"],
+    inspect: ["binary_overview"],
+    decompile: ["procedure_pseudo_code"],
+    function: ["analyze_function"],
+    instructions: ["read_function_instructions"],
+    trace: ["trace_feature"],
+    search: ["search_strings", "search_procedures"],
+    "capture-process": ["capture_process_scenario"],
+    "compare-bundles": ["compare_bundles"],
+});
+/** MCP operations without a dedicated CLI command or direct command alias. */
+export const MCP_TOOLS_WITHOUT_DEDICATED_CLI = Object.freeze([
+    "address_name",
+    "comment",
+    "current_address",
+    "current_procedure",
+    "current_document",
+    "goto_address",
+    "inline_comment",
+    "list_bookmarks",
+    "list_documents",
+    "list_names",
+    "list_procedures",
+    "list_segments",
+    "list_strings",
+    "next_address",
+    "prev_address",
+    "procedure_address",
+    "procedure_assembly",
+    "procedure_callees",
+    "procedure_callers",
+    "procedure_info",
+    "read_bytes",
+    "address_to_file_offset",
+    "procedure_references",
+    "resolve_containing_procedure",
+    "set_address_name",
+    "set_addresses_names",
+    "set_bookmark",
+    "set_comment",
+    "set_current_document",
+    "set_inline_comment",
+    "unset_bookmark",
+    "get_objc_classes",
+    "get_objc_protocols",
+    "batch_decompile",
+    "get_call_graph",
+    "analyze_swift_types",
+    "find_xrefs_to_name",
+    "trace_call_path",
+    "open_binary",
+    "close_binary",
+    "binary_session",
+    "export_evidence_bundle",
+    "import_evidence_bundle",
+    "compare_artifacts",
+    "compare_functions",
+    "find_changed_behavior",
+    "build_call_path",
+    "correlate_static_and_runtime",
+    "verify_reconstruction",
+    "list_unknowns",
+    "record_unknown",
+    "update_unknown",
+    "verify_unknown_resolution",
+    "get_evidence_bundle",
+    "get_navigation_context",
+    "inspect_address_context",
+]);

package/dist/cliElectronCommands.js

@@ -2,14 +2,12 @@ import { Cli, z } from "incur";
 import { inspectElectronPage, listElectronTargets, } from "./application/ElectronObservationService.js";
 import { captureElectronScenario } from "./application/ElectronActiveObservationService.js";
 import { reconcileJavaScriptRuntimeEvidence } from "./application/JavaScriptRuntimeReconciliationService.js";
-import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
 import { CdpElectronProvider } from "./browser/CdpElectronProvider.js";
 import { PlaywrightElectronActiveProvider } from "./browser/PlaywrightElectronActiveProvider.js";
 import { logCliCommand } from "./cliLogging.js";
-import { parseConfig } from "./config.js";
 import { inspectElectronPageInputSchema, listElectronTargetsInputSchema, } from "./domain/electronObservation.js";
 import { electronActiveObservationInputSchema } from "./domain/electronActiveObservation.js";
-import { AnalysisCapabilityUnavailableError, AnalysisInputError, projectAnalysisError, } from "./domain/errors.js";
+import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
 import { parseCliJsonInput } from "./cliJsonInput.js";
 import { electronPageInspectionOptions, javascriptApplicationOptions, } from "./cliObservationOptions.js";
@@ -23,7 +21,7 @@ export const registerElectronCommands = (cli, logger) => {
 };
 const registerElectronActiveCommand = (cli, logger) => {
     cli.command(CLI_COMMANDS.captureElectronScenario, {
-        description: "Run one approved, bounded owned Electron scenario",
+        description: "Run one bounded owned Electron scenario",
         args: z.object({
             inputJson: z
                 .string()
@@ -37,9 +35,7 @@ const registerElectronActiveCommand = (cli, logger) => {
             if (!parsed.success)
                 return inputError("capture_electron_scenario");
             const context = await electronContext();
-            if (!context.ok)
-                return context.error;
-            const result = await captureElectronScenario(context.activeProvider, context.authority, parsed.data);
+            const result = await captureElectronScenario(context.activeProvider, parsed.data);
             return result.ok ? result.value : cliError(result.error);
         }),
     });
@@ -67,20 +63,18 @@ const registerElectronObservationCommands = (cli, logger) => {
 };
 const registerElectronTargetList = (cli, logger) => {
     cli.command(CLI_COMMANDS.listElectronTargets, {
-        description: "List local file pages exposed by Electron CDP",
+        description: "List local file pages exposed by the selected Electron CDP endpoint",
         args: z.object({
             endpoint: z.string().describe("Literal-loopback Electron CDP endpoint"),
         }),
         run: ({ args }) => logCliCommand(logger, "list-electron-targets", async () => {
-            const context = await electronObservationContext("list_electron_targets");
-            if (!context.ok)
-                return context.error;
+            const context = await electronObservationContext();
             const parsed = listElectronTargetsInputSchema.safeParse({
                 cdp_endpoint: args.endpoint,
             });
             if (!parsed.success)
                 return inputError("list_electron_targets");
-            const result = await listElectronTargets(context.provider, context.authority, parsed.data);
+            const result = await listElectronTargets(context.provider, parsed.data);
             return result.ok ? result.value : cliError(result.error);
         }),
     });
@@ -94,9 +88,7 @@ const registerElectronPageInspection = (cli, logger) => {
         }),
         options: electronPageInspectionOptions,
         run: ({ args, options }) => logCliCommand(logger, "inspect-electron-page", async () => {
-            const context = await electronObservationContext("inspect_electron_page");
-            if (!context.ok)
-                return context.error;
+            const context = await electronObservationContext();
             const parsed = inspectElectronPageInputSchema.safeParse({
                 cdp_endpoint: args.endpoint,
                 target_id: args.targetId,
@@ -105,7 +97,7 @@ const registerElectronPageInspection = (cli, logger) => {
             });
             if (!parsed.success)
                 return inputError("inspect_electron_page");
-            const result = await inspectElectronPage(context.provider, context.authority, parsed.data);
+            const result = await inspectElectronPage(context.provider, parsed.data);
             return result.ok ? result.value : cliError(result.error);
         }),
     });
@@ -114,7 +106,7 @@ const registerJavaScriptApplicationCommand = (cli, logger) => {
     cli.command(CLI_COMMANDS.analyzeJavaScriptApplication, {
         description: "Statically reconstruct a local JavaScript/Electron application",
         args: z.object({
-            path: z.string().describe("Absolute ASAR or extracted application path"),
+            path: z.string().describe("ASAR or extracted application path"),
         }),
         options: javascriptApplicationOptions,
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.analyzeJavaScriptApplication, () => runCliJavaScriptApplicationAnalysis({
@@ -124,31 +116,13 @@ const registerJavaScriptApplicationCommand = (cli, logger) => {
     });
 };
 const electronContext = async () => {
-    const config = parseConfig(process.env);
-    if (!config.ok)
-        return { ok: false, error: cliError(config.error) };
-    const authority = await loadConfiguredPermissionAuthority(config.value);
-    if (!authority.ok)
-        return { ok: false, error: cliError(authority.error) };
     return {
         ok: true,
-        authority: authority.value,
         provider: new CdpElectronProvider(),
         activeProvider: new PlaywrightElectronActiveProvider(),
-        observationPolicy: config.value.electronObservationPolicy,
     };
 };
-const electronObservationContext = async (operation) => {
-    const context = await electronContext();
-    if (!context.ok)
-        return context;
-    if (context.observationPolicy.status === "disabled")
-        return {
-            ok: false,
-            error: cliError(new AnalysisCapabilityUnavailableError("rea-cdp-electron", operation, "Electron observation is disabled; enable REA_ELECTRON_OBSERVE_ENABLED to authorize loopback endpoints")),
-        };
-    return context;
-};
+const electronObservationContext = electronContext;
 const inputError = (operation) => cliError(new AnalysisInputError(operation));
 const cliError = (error) => ({
     error: "Electron analysis failed",

package/dist/cliJavaScriptRuntimeCommands.js

@@ -1,12 +1,10 @@
 import { Cli, z } from "incur";
 import { listJavaScriptRuntimeTargets, observeJavaScriptRuntime, } from "./application/JavaScriptRuntimeObservationService.js";
-import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
 import { V8InspectorProvider } from "./browser/V8InspectorProvider.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
 import { logCliCommand } from "./cliLogging.js";
-import { parseConfig } from "./config.js";
 import { javascriptRuntimeKindSchema, listJavaScriptRuntimeTargetsInputSchema, observeJavaScriptRuntimeInputSchema, } from "./domain/javascriptRuntimeObservation.js";
-import { AnalysisCapabilityUnavailableError, AnalysisInputError, projectAnalysisError, } from "./domain/errors.js";
+import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
 const observeOptionsSchema = z.object({
     runtimeKind: javascriptRuntimeKindSchema
         .optional()
@@ -26,15 +24,13 @@ export const registerJavaScriptRuntimeObservationCommands = (cli, logger) => {
             endpoint: z.string().describe("Literal-loopback Inspector endpoint"),
         }),
         run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.listJavaScriptRuntimeTargets, async () => {
-            const context = await runtimeContext("list_javascript_runtime_targets");
-            if (!context.ok)
-                return context.error;
+            const context = runtimeContext();
             const parsed = listJavaScriptRuntimeTargetsInputSchema.safeParse({
                 inspector_endpoint: args.endpoint,
             });
             if (!parsed.success)
                 return inputError("list_javascript_runtime_targets");
-            const result = await listJavaScriptRuntimeTargets(context.provider, context.authority, parsed.data);
+            const result = await listJavaScriptRuntimeTargets(context.provider, parsed.data);
             return result.ok ? result.value : cliError(result.error);
         }),
     });
@@ -48,9 +44,7 @@ export const registerJavaScriptRuntimeObservationCommands = (cli, logger) => {
         }),
         options: observeOptionsSchema,
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.observeJavaScriptRuntime, async () => {
-            const context = await runtimeContext("observe_javascript_runtime");
-            if (!context.ok)
-                return context.error;
+            const context = runtimeContext();
             const parsed = observeJavaScriptRuntimeInputSchema.safeParse({
                 inspector_endpoint: args.endpoint,
                 target_id: args.targetId,
@@ -59,30 +53,12 @@ export const registerJavaScriptRuntimeObservationCommands = (cli, logger) => {
             });
             if (!parsed.success)
                 return inputError("observe_javascript_runtime");
-            const result = await observeJavaScriptRuntime(context.provider, context.authority, parsed.data);
+            const result = await observeJavaScriptRuntime(context.provider, parsed.data);
             return result.ok ? result.value : cliError(result.error);
         }),
     });
 };
-const runtimeContext = async (operation) => {
-    const config = parseConfig(process.env);
-    if (!config.ok)
-        return { ok: false, error: cliError(config.error) };
-    const policy = config.value.v8InspectorObservationPolicy;
-    if (policy.status === "disabled")
-        return {
-            ok: false,
-            error: cliError(new AnalysisCapabilityUnavailableError("rea-v8-inspector", operation, "V8 Inspector observation is disabled; enable REA_V8_INSPECTOR_OBSERVE_ENABLED to authorize loopback endpoints")),
-        };
-    const authority = await loadConfiguredPermissionAuthority(config.value);
-    if (!authority.ok)
-        return { ok: false, error: cliError(authority.error) };
-    return {
-        ok: true,
-        authority: authority.value,
-        provider: new V8InspectorProvider(),
-    };
-};
+const runtimeContext = () => ({ provider: new V8InspectorProvider() });
 const inputError = (operation) => cliError(new AnalysisInputError(operation));
 const cliError = (error) => ({
     error: "JavaScript runtime observation failed",

package/dist/cliJsonInput.js

@@ -8,7 +8,7 @@ export const parseCliJsonInput = async (value, operation) => {
     if (["{", "["].includes(value.trimStart()[0] ?? ""))
         return { ok: false, error: inputError(operation) };
     try {
-        const parsed = parseJson(await readFile(value, "utf8"));
+        const parsed = parseJson(await readFile(value));
         return parsed === undefined
             ? jsonFileError(value, operation, "invalid-json")
             : { ok: true, value: parsed };
@@ -19,7 +19,9 @@ export const parseCliJsonInput = async (value, operation) => {
 };
 const parseJson = (value) => {
     try {
-        return JSON.parse(value);
+        return JSON.parse(typeof value === "string"
+            ? value
+            : new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(value));
     }
     catch {
         return undefined;

package/dist/cliLogging.js

@@ -1,23 +1,27 @@
+import { analysisCliErrorEnvelopeSchema, analysisErrorProjectionSchema, } from "./contracts/errorSchemas.js";
+import { AnalysisError, projectAnalysisError, } from "./domain/errors.js";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** Identify caller-visible CLI outcomes that mean the requested operation failed. */
 export const isCliOperationFailure = (value) => {
     if (!isRecord(value))
         return false;
-    if (typeof value.error === "string")
+    if (isRecord(value.error) &&
+        analysisErrorProjectionSchema.safeParse(value.error).success)
+        return true;
+    if (analysisCliErrorEnvelopeSchema.safeParse(value).success)
+        return true;
+    if (analysisErrorProjectionSchema.safeParse(value).success)
         return true;
     if (value.healthy === false)
         return true;
-    return (value.status === "failed" ||
-        value.status === "needs_confirmation" ||
-        value.status === "needs_human" ||
-        value.status === "planned");
+    return false;
 };
 /** Log one CLI command with duration and a stable success or failure status. */
-export const logCliCommand = async (logger, command, execute) => {
+export const logCliCommand = async (logger, command, execute, isCommandFailure) => {
     const startedAt = performance.now();
     try {
         const value = await execute();
-        const failed = isCliOperationFailure(value);
+        const failed = isCommandFailure?.(value) ?? isCliOperationFailure(value);
         logger[failed ? "error" : "info"]({
             command,
             durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
@@ -28,11 +32,16 @@ export const logCliCommand = async (logger, command, execute) => {
         return value;
     }
     catch (cause) {
+        process.exitCode = 1;
         logger.error({
             command,
             durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
             status: "error",
         }, "CLI command failed");
+        if (cause instanceof AnalysisError) {
+            process.exitCode = 1;
+            return projectAnalysisError(cause);
+        }
         throw cause;
     }
 };

package/dist/cliObservationOptions.js

@@ -11,7 +11,7 @@ export const browserScopeOptions = {
     allowedOrigins: z
         .array(z.string().min(1))
         .optional()
-        .describe("Exact origins to observe; defaults to REA_BROWSER_ALLOWED_ORIGINS_JSON"),
+        .describe("Optional exact-origin filter"),
 };
 export const browserPageInspectionOptions = z.object({
     ...browserScopeOptions,

package/dist/cliOutput.js

@@ -2,8 +2,6 @@ const SAFE_VALIDATION_MESSAGE = "REA could not read the command arguments. Run `
 const UNSUPPORTED_OUTPUT_COMBINATION_MESSAGE = "Token windows cannot preserve structured output. Remove --token-limit/--token-offset and use --filter-output or command pagination.";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const validationError = (value) => {
-    if (!isRecord(value))
-        return undefined;
     if (value.code === "VALIDATION_ERROR")
         return value;
     if (value.ok === false && isRecord(value.error))
@@ -71,6 +69,8 @@ export const sanitizeCliOutput = (output) => {
     if (trimmed.startsWith("{")) {
         try {
             const parsed = JSON.parse(trimmed);
+            if (!isRecord(parsed))
+                return output;
             const error = validationError(parsed);
             if (error !== undefined) {
                 const safeError = {
@@ -79,8 +79,6 @@ export const sanitizeCliOutput = (output) => {
                 };
                 if (error === parsed)
                     return `${JSON.stringify(safeError)}\n`;
-                if (!isRecord(parsed))
-                    return output;
                 return `${JSON.stringify({ ...parsed, error: safeError })}\n`;
             }
         }

package/dist/cliProcessCommands.js

@@ -1,18 +1,13 @@
 import { Cli, z } from "incur";
-import { captureProcessScenarioFile, compareProcessEvidenceFiles, } from "./application/ProcessCli.js";
+import { captureProcessScenarioFile, compareProcessEvidenceFiles, isProcessCliFailure, } from "./application/ProcessCli.js";
 import { logCliCommand } from "./cliLogging.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
-import { parseCliJsonInput } from "./cliJsonInput.js";
-import { replayMachineRunInputSchema, runReplayMachine, } from "./domain/replayMachineRun.js";
-import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
-import { projectInputIssues } from "./domain/inputIssueProjection.js";
-/** Register process capture one-shot commands through shared application services. */
-export const registerProcessCommands = (cli, logger) => {
-    registerReplayMachineCommand(cli, logger);
+/** Register direct process capture and comparison commands. */
+export const registerProcessCommands = (cli, logger, environment = process.env) => {
     cli.command(CLI_COMMANDS.captureProcess, {
-        description: "Capture one approved process capture JSON scenario",
+        description: "Capture one caller-selected process scenario",
         args: z.object({ scenario: z.string().describe("Scenario JSON path") }),
-        run: ({ args }) => logCliCommand(logger, "capture-process", () => captureProcessScenarioFile(args.scenario)),
+        run: ({ args }) => logCliCommand(logger, "capture-process", () => captureProcessScenarioFile(args.scenario, environment), isProcessCliFailure),
     });
     cli.command(CLI_COMMANDS.compareProcessCaptures, {
         description: "Compare two process capture Evidence JSON files",
@@ -24,28 +19,6 @@ export const registerProcessCommands = (cli, logger) => {
                 .optional()
                 .describe("Optional partial-order or finite-trace specification path"),
         }),
-        run: ({ args }) => logCliCommand(logger, "compare-process-captures", () => compareProcessEvidenceFiles(args.left, args.right, args.traceSpec)),
-    });
-};
-const registerReplayMachineCommand = (cli, logger) => {
-    cli.command(CLI_COMMANDS.runReplayMachine, {
-        description: "Run ordered protocol events directly through a finite replay machine",
-        args: z.object({
-            inputJson: z.string().describe("Inline replay JSON or JSON file path"),
-        }),
-        run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.runReplayMachine, async () => {
-            const input = await parseCliJsonInput(args.inputJson, CLI_COMMANDS.runReplayMachine);
-            if (!input.ok)
-                return input.error;
-            const parsed = replayMachineRunInputSchema.safeParse(input.value);
-            return parsed.success
-                ? runReplayMachine(parsed.data)
-                : {
-                    error: "Process command failed",
-                    ...projectAnalysisError(new AnalysisInputError(CLI_COMMANDS.runReplayMachine, {
-                        cause: parsed.error,
-                    }, projectInputIssues(parsed.error.issues, input.value))),
-                };
-        }),
+        run: ({ args }) => logCliCommand(logger, "compare-process-captures", () => compareProcessEvidenceFiles(args.left, args.right, args.traceSpec), isProcessCliFailure),
     });
 };