rea-agents 6.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (343) hide show
  1. package/README.md +23 -17
  2. package/bridge/android/ReaJadxBridge.java +14 -5
  3. package/bridge/ghidra/ReaGhidraBridge.java +173 -47
  4. package/bridge/hopper_bridge.py +310 -128
  5. package/bridge/mitmproxy/capture.py +0 -2
  6. package/bridge/native/rea_lldb_tracer.py +630 -94
  7. package/bridge/process/ProcessRunTokenReader.swift +39 -5
  8. package/bridge/pwntools/recorded_crash_impl.py +4 -0
  9. package/dist/android/JadxConfiguration.js +196 -33
  10. package/dist/android/JadxMcpTransport.js +4 -0
  11. package/dist/android/JadxProtocol.js +6 -0
  12. package/dist/android/JadxProvider.js +19 -2
  13. package/dist/android/JadxSession.js +23 -4
  14. package/dist/application/AnalysisContextQueries.js +8 -35
  15. package/dist/application/AnalysisDocument.js +32 -0
  16. package/dist/application/AppBundleExecutable.js +67 -21
  17. package/dist/application/CallPathTracing.js +19 -3
  18. package/dist/application/CapabilityInventory.js +6 -3
  19. package/dist/application/ClientConfigurationDocument.js +871 -6
  20. package/dist/application/ClientRegistrationIdentity.js +26 -5
  21. package/dist/application/ClientRegistrationStatus.js +29 -14
  22. package/dist/application/DirectAnalysis.js +27 -37
  23. package/dist/application/Doctor.js +4 -2
  24. package/dist/application/DoctorScope.js +25 -13
  25. package/dist/application/EnhancedLiteralTracing.js +22 -25
  26. package/dist/application/EnhancedTools.js +13 -11
  27. package/dist/application/EvidenceBundleFiles.js +23 -11
  28. package/dist/application/FunctionAnalysisEvidence.js +2 -3
  29. package/dist/application/InventoryProjectionEvidence.js +4 -3
  30. package/dist/application/InvestigationProviders.js +3 -2
  31. package/dist/application/JsonFiles.js +50 -28
  32. package/dist/application/ProcedureAddressResolution.js +11 -0
  33. package/dist/application/ReconstructionCoverageService.js +7 -4
  34. package/dist/application/ReconstructionObligationLedgerService.js +4 -3
  35. package/dist/application/Setup.js +13 -1
  36. package/dist/application/SetupClientConfiguration.js +10 -15
  37. package/dist/application/SetupHost.js +5 -2
  38. package/dist/application/SetupPlan.js +5 -3
  39. package/dist/application/SupportedClients.js +34 -1
  40. package/dist/application/Uninstall.js +4 -3
  41. package/dist/application/Update.js +18 -3
  42. package/dist/application/UpdateRuntime.js +46 -25
  43. package/dist/application/WebModuleTraceService.js +4 -2
  44. package/dist/application/WebNetworkCaptureService.js +4 -2
  45. package/dist/application/WebRuntimeService.js +5 -3
  46. package/dist/application/WebScriptExportService.js +2 -2
  47. package/dist/application/WebSourceLocationService.js +4 -2
  48. package/dist/application/WorkflowEvidence.js +82 -0
  49. package/dist/application/binary/AnalysisProviderEvaluation.js +21 -5
  50. package/dist/application/binary/AnalysisProviderRegistry.js +2 -0
  51. package/dist/application/binary/AnalysisSnapshotCache.js +3 -6
  52. package/dist/application/binary/BinarySession.js +95 -68
  53. package/dist/application/binary/BinarySessionOpen.js +3 -3
  54. package/dist/application/binary/BinarySessionRecords.js +25 -3
  55. package/dist/application/binary/BinarySessionStatus.js +17 -1
  56. package/dist/application/binary/CompositeProvider.js +13 -0
  57. package/dist/application/binary/LazyAnalysisProvider.js +3 -0
  58. package/dist/application/binaryDiagnostics/BinaryLayoutService.js +4 -2
  59. package/dist/application/binaryDiagnostics/RecordedCrashService.js +4 -2
  60. package/dist/application/evm/EvmInterfaceService.js +4 -2
  61. package/dist/application/investigation/EvidenceLedger.js +21 -7
  62. package/dist/application/investigation/InvestigationRecords.js +8 -0
  63. package/dist/application/javascript/JavaScriptAnalysisControl.js +34 -0
  64. package/dist/application/javascript/JavaScriptApplicationEvidence.js +24 -3
  65. package/dist/application/javascript/JavaScriptApplicationEvidenceGraph.js +19 -2
  66. package/dist/application/javascript/JavaScriptApplicationService.js +22 -15
  67. package/dist/application/javascript/JavaScriptApplicationWorkflowService.js +5 -5
  68. package/dist/application/javascript/JavaScriptArtifactAnalysis.js +5 -4
  69. package/dist/application/javascript/JavaScriptArtifactGraphBuilder.js +39 -7
  70. package/dist/application/javascript/JavaScriptArtifactPathResolution.js +6 -3
  71. package/dist/application/javascript/JavaScriptArtifactReconstruction.js +11 -3
  72. package/dist/application/javascript/JavaScriptModuleRelationships.js +37 -8
  73. package/dist/application/javascript/JavaScriptRecoveryService.js +4 -2
  74. package/dist/application/javascript/JavaScriptRuntimeObservationService.js +3 -1
  75. package/dist/application/javascript/JavaScriptRuntimeReconciliationService.js +3 -3
  76. package/dist/application/javascript/JavaScriptSemanticGraphBuilder.js +63 -61
  77. package/dist/application/javascript/JavaScriptSemanticGraphValueProjection.js +23 -1
  78. package/dist/application/managed/ManagedApplicationGraphService.js +4 -3
  79. package/dist/application/managed/ManagedMemberComparisonService.js +7 -4
  80. package/dist/application/managed/ManagedNativeVerificationService.js +4 -3
  81. package/dist/application/managed/ManagedReconstructionService.js +4 -3
  82. package/dist/application/process/ProcessCli.js +14 -6
  83. package/dist/application/process/ProcessEvidence.js +4 -3
  84. package/dist/application/workflowInputError.js +18 -0
  85. package/dist/artifacts/ArtifactProvider.js +12 -2
  86. package/dist/artifacts/MachOSliceArtifactReader.js +98 -14
  87. package/dist/artifacts/NativeDmgArtifactReader.js +13 -6
  88. package/dist/artifacts/apple/AppleAssetCatalogAnalysis.js +22 -3
  89. package/dist/artifacts/apple/InterfaceBuilderAnalysis.js +176 -56
  90. package/dist/artifacts/apple/InterfaceBuilderDecodeBudget.js +195 -0
  91. package/dist/artifacts/apple/KeyedArchiveReader.js +36 -22
  92. package/dist/artifacts/apple/MachoLoadCommandReader.js +92 -31
  93. package/dist/artifacts/apple/NibArchive.js +81 -14
  94. package/dist/artifacts/apple/NibViewHierarchy.js +10 -3
  95. package/dist/artifacts/apple/PlistNumberLiterals.js +164 -0
  96. package/dist/artifacts/inventory/ArtifactGraphConstruction.js +13 -8
  97. package/dist/artifacts/inventory/scanCanonical.js +11 -14
  98. package/dist/artifacts/javascript/JavaScriptArtifactFiles.js +6 -2
  99. package/dist/browser/CdpCaptureCompleteness.js +2 -0
  100. package/dist/browser/CdpCaptureEventHandlers.js +76 -11
  101. package/dist/browser/CdpCaptureEventTypes.js +5 -1
  102. package/dist/browser/CdpCaptureEvents.js +25 -0
  103. package/dist/browser/CdpConnection.js +30 -11
  104. package/dist/browser/CdpOptionalCommand.js +2 -3
  105. package/dist/browser/CdpPageCapture.js +23 -1
  106. package/dist/browser/PlaywrightElectronActiveActions.js +32 -23
  107. package/dist/browser/PlaywrightElectronActiveProjection.js +141 -0
  108. package/dist/browser/PlaywrightElectronActiveProvider.js +123 -124
  109. package/dist/browser/WebSourceMapFetcher.js +426 -72
  110. package/dist/browser/assets/LocalWebScriptArtifacts.js +2 -2
  111. package/dist/browser/history/CaptureFailures.js +37 -1
  112. package/dist/browser/history/CaptureRelease.js +5 -0
  113. package/dist/browser/history/HarCaptureAdapter.js +3 -3
  114. package/dist/browser/history/HarJson.js +3 -2
  115. package/dist/browser/history/HistoricalCaptureDecoder.js +4 -2
  116. package/dist/cli/analysisSelector.js +23 -0
  117. package/dist/cli/applicationCommands.js +2 -3
  118. package/dist/cli/coreBinaryCommands.js +70 -12
  119. package/dist/cli/electronCommands.js +7 -6
  120. package/dist/cli/javascriptApplicationAnalysis.js +7 -3
  121. package/dist/cli/jsonOutput.js +4 -99
  122. package/dist/cli/nativeCallCommands.js +2 -3
  123. package/dist/cli/webRuntimeCommands.js +8 -8
  124. package/dist/cli.js +2 -1
  125. package/dist/cliCommandNames.js +0 -1
  126. package/dist/cliJsonInput.js +9 -4
  127. package/dist/config/environment.js +4 -0
  128. package/dist/config/ghidraStartupTimeout.js +17 -0
  129. package/dist/config/mcpResponseBudget.js +22 -0
  130. package/dist/config/parseConfig.js +2 -1
  131. package/dist/contracts/enhancedInputs.js +5 -3
  132. package/dist/contracts/enhancedToolContracts.js +3 -3
  133. package/dist/contracts/hopperMemoryContracts.js +2 -5
  134. package/dist/contracts/javascript/electronToolContracts.js +1 -1
  135. package/dist/contracts/managed/managedToolContracts.js +2 -4
  136. package/dist/contracts/native/nativeToolContracts.js +4 -2
  137. package/dist/contracts/officialToolContracts.js +14 -15
  138. package/dist/contracts/promptContracts.js +3 -3
  139. package/dist/contracts/sessionLifecycleInputs.js +3 -7
  140. package/dist/contracts/sessionStatusContract.js +2 -4
  141. package/dist/contracts/sessionToolContracts.js +4 -6
  142. package/dist/contracts/sessionToolSchemas.js +2 -5
  143. package/dist/contracts/toolContractExamples.js +0 -1
  144. package/dist/contracts/toolContractHelpers.js +4 -1
  145. package/dist/contracts/toolEffects.js +0 -1
  146. package/dist/contracts/toolOutputSchemaGroups.js +28 -27
  147. package/dist/contracts/toolOutputSchemaPrimitives.js +18 -0
  148. package/dist/contracts/toolSchemaMetadata.js +69 -10
  149. package/dist/contracts/webNetworkCaptureToolContracts.js +1 -1
  150. package/dist/domain/analysisErrorBase.js +8 -3
  151. package/dist/domain/analysisErrorCore.js +3 -1
  152. package/dist/domain/analysisErrorPresentation.js +72 -17
  153. package/dist/domain/analysisErrorProjection.js +106 -27
  154. package/dist/domain/android/androidAnalysis.js +2 -4
  155. package/dist/domain/android/androidApplication.js +17 -9
  156. package/dist/domain/apple/appleApplication.js +41 -14
  157. package/dist/domain/apple/dyldEnvironment.js +73 -0
  158. package/dist/domain/apple/dylibResolution.js +120 -9
  159. package/dist/domain/apple/dylibResolutionFindings.js +9 -7
  160. package/dist/domain/apple/interfaceBuilderGraph.js +25 -13
  161. package/dist/domain/apple/interfaceBuilderKeyedArchive.js +13 -3
  162. package/dist/domain/apple/keyedArchive.js +9 -1
  163. package/dist/domain/apple/machoContainer.js +54 -0
  164. package/dist/domain/apple/plistNumbers.js +76 -0
  165. package/dist/domain/artifactIdentity.js +29 -0
  166. package/dist/domain/artifactInventoryEvidence.js +19 -24
  167. package/dist/domain/bridgeCandidateProjection.js +71 -0
  168. package/dist/domain/browserCompleteness.js +1 -0
  169. package/dist/domain/browserObservationError.js +24 -5
  170. package/dist/domain/browserScenarioValues.js +2 -6
  171. package/dist/domain/bundleComparison.js +3 -2
  172. package/dist/domain/canonicalJsonDigestSteps.js +133 -0
  173. package/dist/domain/canonicalOrdering.js +9 -5
  174. package/dist/domain/changedBehavior.js +6 -6
  175. package/dist/domain/comparisonSourceEvidence.js +40 -0
  176. package/dist/domain/configurationErrors.js +1 -1
  177. package/dist/domain/evidence.js +64 -9
  178. package/dist/domain/evidenceBundle.js +42 -1
  179. package/dist/domain/evidenceErrors.js +12 -1
  180. package/dist/domain/explicitSensitiveFailure.js +17 -1
  181. package/dist/domain/firmware/firmwareAnalysis.js +6 -7
  182. package/dist/domain/hopperErrors.js +23 -2
  183. package/dist/domain/hopperValues.js +51 -8
  184. package/dist/domain/immutableJson.js +114 -0
  185. package/dist/domain/inputIssueProjection.js +3 -0
  186. package/dist/domain/javascript/electronActiveObservation.js +30 -4
  187. package/dist/domain/javascript/electronStaticAnalysisValues.js +6 -12
  188. package/dist/domain/javascript/javascriptApplicationAnalysis.js +71 -23
  189. package/dist/domain/javascript/javascriptApplicationGraph.js +13 -0
  190. package/dist/domain/javascript/javascriptAstValues.js +20 -0
  191. package/dist/domain/javascript/javascriptRecovery.js +3 -8
  192. package/dist/domain/javascript/javascriptSemanticAnalysis.js +97 -2
  193. package/dist/domain/javascript/javascriptSemanticCoverage.js +6 -5
  194. package/dist/domain/javascript/javascriptSemanticDataEffectHelpers.js +9 -17
  195. package/dist/domain/javascript/javascriptSemanticDataEffects.js +22 -5
  196. package/dist/domain/javascript/javascriptSemanticGraph.js +13 -0
  197. package/dist/domain/javascript/javascriptSemanticGraphSchemas.js +1 -0
  198. package/dist/domain/javascript/javascriptSemanticPrimitives.js +25 -17
  199. package/dist/domain/javascript/javascriptSemanticQuerySchemas.js +8 -4
  200. package/dist/domain/javascript/javascriptSemanticResourceLimits.js +77 -0
  201. package/dist/domain/javascript/javascriptSemanticValues.js +83 -11
  202. package/dist/domain/javascript/javascriptSourceParser.js +6 -2
  203. package/dist/domain/javascript/javascriptStaticAnalysis.js +22 -17
  204. package/dist/domain/javascript/javascriptStaticAnalysisBundler.js +5 -3
  205. package/dist/domain/javascript/javascriptStaticAnalysisCalls.js +14 -4
  206. package/dist/domain/javascript/javascriptStaticAnalysisFindings.js +66 -7
  207. package/dist/domain/javascript/javascriptStaticAnalysisHelpers.js +28 -16
  208. package/dist/domain/javascript/javascriptStaticAnalysisState.js +3 -2
  209. package/dist/domain/jsonSerialization.js +109 -0
  210. package/dist/domain/jsonValue.js +90 -6
  211. package/dist/domain/localPath.js +6 -0
  212. package/dist/domain/managed/managedApplicationGraph.js +10 -10
  213. package/dist/domain/managed/managedInspectionEvidence.js +16 -0
  214. package/dist/domain/managed/managedMemberComparisonMatch.js +5 -9
  215. package/dist/domain/managed/managedNativeVerification.js +3 -9
  216. package/dist/domain/native/fileOffsetPartialObservation.js +1 -0
  217. package/dist/domain/native/nativeCallObservation.js +33 -11
  218. package/dist/domain/native/nativeCallPartialObservation.js +33 -0
  219. package/dist/domain/process/processCapture.js +8 -4
  220. package/dist/domain/process/processComparison.js +38 -4
  221. package/dist/domain/process/processScenario.js +11 -10
  222. package/dist/domain/propertyListKeys.js +1 -1
  223. package/dist/domain/propertyListXmlText.js +19 -0
  224. package/dist/domain/providerAdapterError.js +1 -1
  225. package/dist/domain/providerOperationHealth.js +54 -0
  226. package/dist/domain/reconstructionVerification.js +6 -43
  227. package/dist/domain/reconstructionVerificationSchemas.js +2 -2
  228. package/dist/domain/staticRuntimeCorrelation.js +6 -43
  229. package/dist/domain/webBundleAnalysis.js +20 -8
  230. package/dist/domain/webBundleAnalyzerInspection.js +13 -8
  231. package/dist/domain/webBundleAnalyzerResult.js +41 -2
  232. package/dist/domain/webRuntime.js +19 -5
  233. package/dist/domain/webSourceLocation.js +1 -0
  234. package/dist/firmware/FirmwareFiles.js +1 -1
  235. package/dist/generatedPackageMetadata.js +1 -1
  236. package/dist/ghidra/GhidraAnalysisProfile.js +5 -0
  237. package/dist/ghidra/GhidraClient.js +47 -14
  238. package/dist/ghidra/GhidraDiagnostics.js +7 -7
  239. package/dist/ghidra/GhidraFunctionValues.js +10 -7
  240. package/dist/ghidra/GhidraInstallation.js +18 -21
  241. package/dist/ghidra/GhidraInventoryValues.js +14 -4
  242. package/dist/ghidra/GhidraJavaLaunch.js +62 -0
  243. package/dist/ghidra/GhidraLauncher.js +33 -16
  244. package/dist/ghidra/GhidraProviderCapabilities.js +14 -2
  245. package/dist/ghidra/GhidraProviderClient.js +23 -12
  246. package/dist/ghidra/GhidraSessionError.js +11 -7
  247. package/dist/ghidra/GhidraTargetSnapshot.js +47 -12
  248. package/dist/ghidra/GhidraTransport.js +20 -0
  249. package/dist/hopper/BridgeLauncher.js +31 -11
  250. package/dist/hopper/HopperAnalysisProfile.js +62 -4
  251. package/dist/hopper/HopperCleanup.js +15 -3
  252. package/dist/hopper/HopperClient.js +222 -14
  253. package/dist/hopper/HopperFileOffset.js +237 -0
  254. package/dist/hopper/HopperMachOImage.js +196 -0
  255. package/dist/hopper/HopperOperationStage.js +6 -0
  256. package/dist/hopper/HopperProvider.js +63 -9
  257. package/dist/hopper/HopperProviderCapabilities.js +19 -1
  258. package/dist/hopper/HopperRegexSearch.js +137 -0
  259. package/dist/hopper/HopperRegexWorker.js +27 -0
  260. package/dist/hopper/HopperRequestQueue.js +68 -19
  261. package/dist/hopper/HopperTargetLease.js +3 -2
  262. package/dist/inspector/JavaScriptRuntimeScope.js +9 -1
  263. package/dist/inspector/V8InspectorCaptureProjection.js +8 -3
  264. package/dist/inspector/V8InspectorProvider.js +47 -11
  265. package/dist/javascript/sourceMaps/DecodedSourceMap.js +47 -0
  266. package/dist/javascript/sourceMaps/SourceMapCommand.js +16 -0
  267. package/dist/javascript/sourceMaps/SourceMapFormat.js +79 -31
  268. package/dist/javascript/sourceMaps/TraceSourceMap.js +14 -28
  269. package/dist/mcpDoctor.js +62 -2
  270. package/dist/native/AppleDispatchCoverage.js +47 -6
  271. package/dist/native/AppleDispatchDecodeFacts.js +6 -0
  272. package/dist/native/AppleDispatchMetadata.js +6 -3
  273. package/dist/native/AppleMachoFixups.js +48 -24
  274. package/dist/native/AppleMachoSelection.js +32 -16
  275. package/dist/native/AppleObjcCategories.js +6 -2
  276. package/dist/native/AppleObjcDispatchFacets.js +5 -2
  277. package/dist/native/AppleObjcProperties.js +2 -1
  278. package/dist/native/AppleSwiftDispatchFacets.js +27 -21
  279. package/dist/native/AppleSwiftVtables.js +21 -15
  280. package/dist/native/CommandRunner.js +81 -84
  281. package/dist/native/LldbCallTracer.js +365 -102
  282. package/dist/native/LldbRetainedObservations.js +178 -0
  283. package/dist/native/NativeCallObservation.js +62 -3
  284. package/dist/native/NativeMacOSProvider.js +98 -17
  285. package/dist/native/SignatureTargetBinding.js +155 -0
  286. package/dist/native/parsers/lipo.js +71 -1
  287. package/dist/native/pwndbg/PwndbgCoreContext.js +25 -5
  288. package/dist/native/pwntools/RecordedCrashStructureBindings.js +2 -0
  289. package/dist/process/DarwinProcessRunTokenReader.js +8 -9
  290. package/dist/process/ExecFileOutput.js +20 -0
  291. package/dist/process/OwnedCommand.js +7 -2
  292. package/dist/process/ProcessOwnership.js +203 -53
  293. package/dist/process/ProcessOwnershipObservation.js +49 -4
  294. package/dist/process/ProviderProcess.js +38 -7
  295. package/dist/process/capture/ProcessCaptureError.js +2 -2
  296. package/dist/process/capture/ProcessCaptureLifecycle.js +100 -34
  297. package/dist/server/EvidenceMcpServer.js +146 -0
  298. package/dist/server/createServer.js +15 -8
  299. package/dist/server/registerAndroidTools.js +2 -4
  300. package/dist/server/registerApplicationTools/helpers.js +2 -4
  301. package/dist/server/registerArtifactComparisonTool.js +11 -7
  302. package/dist/server/registerBinaryDiagnosticsTools.js +2 -4
  303. package/dist/server/registerBrowserScenarioTool.js +2 -4
  304. package/dist/server/registerBrowserTools.js +2 -4
  305. package/dist/server/registerBundleComparisonTool.js +2 -3
  306. package/dist/server/registerCloseLifecycleTool.js +8 -18
  307. package/dist/server/registerElectronTools.js +2 -4
  308. package/dist/server/registerEnhancedTools.js +18 -59
  309. package/dist/server/registerEvidenceTools.js +2 -4
  310. package/dist/server/registerEvmTools.js +2 -4
  311. package/dist/server/registerFirmwareTools.js +2 -4
  312. package/dist/server/registerFunctionComparisonTool.js +10 -6
  313. package/dist/server/registerInvestigationTools.js +7 -7
  314. package/dist/server/registerJavaScriptRecoveryTool.js +2 -4
  315. package/dist/server/registerJavaScriptRuntimeObservationTools.js +2 -4
  316. package/dist/server/registerManagedWorkflowTools/compareManagedMembers.js +2 -4
  317. package/dist/server/registerManagedWorkflowTools/importManagedReconstruction.js +2 -4
  318. package/dist/server/registerManagedWorkflowTools/projectManagedApplicationGraph.js +2 -4
  319. package/dist/server/registerManagedWorkflowTools/verifyManagedNativeBoundaries.js +2 -4
  320. package/dist/server/registerOfficialTools.js +2 -4
  321. package/dist/server/registerProcessComparisonTool.js +71 -45
  322. package/dist/server/registerRecordedCrashTools.js +2 -4
  323. package/dist/server/registerSessionRecordTools.js +5 -6
  324. package/dist/server/registerSessionStatusTool.js +17 -3
  325. package/dist/server/registerSessionTools.js +11 -3
  326. package/dist/server/registerWebModuleTool.js +2 -4
  327. package/dist/server/registerWebNetworkCaptureTool.js +2 -4
  328. package/dist/server/registerWebRuntimeTools.js +3 -7
  329. package/dist/server/registerWebScriptTool.js +2 -4
  330. package/dist/server/registerWebSourceLocationTool.js +2 -4
  331. package/dist/server/runDerivedOperation.js +15 -3
  332. package/dist/server/sessionAvailabilityPolicy.js +0 -1
  333. package/dist/server/toolRegistrationOptions.js +2 -2
  334. package/dist/server/toolResult.js +62 -10
  335. package/dist/server/toolResultEncoding.js +33 -0
  336. package/install.sh +1 -1
  337. package/native/windows/build/manifest.json +1 -1
  338. package/package.json +8 -3
  339. package/scripts/electron-active-hook-boundaries.cjs +18 -20
  340. package/scripts/electron-active-hook.cjs +241 -37
  341. package/skills/reverse-engineer-anything/SKILL.md +11 -3
  342. package/skills/reverse-engineer-anything/references/javascript-applications.md +8 -1
  343. package/dist/ghidra/GhidraDefaults.js +0 -2
@@ -27,9 +27,9 @@ export const parseCliJsonInput = async (value, operation) => {
27
27
  /**
28
28
  * Resolve named string fields of CLI-supplied JSON against the operator
29
29
  * working directory. Each entry is a key path from the document root; only
30
- * fields holding strings are resolved, everything else passes through
31
- * untouched. Shared MCP contracts reject relative paths, so CLI workflows
32
- * resolve operator-relative values before validation.
30
+ * fields holding nonblank strings are resolved, everything else passes through
31
+ * untouched so shared schemas can reject blank paths. Shared MCP contracts reject
32
+ * relative paths, so CLI workflows resolve operator-relative values before validation.
33
33
  */
34
34
  export const resolveCliJsonPaths = (value, paths) => {
35
35
  let resolved = value;
@@ -45,7 +45,12 @@ const resolveJsonPath = (value, keys) => {
45
45
  if (key !== head)
46
46
  return [key, entry];
47
47
  if (tail.length === 0)
48
- return [key, typeof entry === "string" ? resolve(entry) : entry];
48
+ return [
49
+ key,
50
+ typeof entry === "string" && entry.trim().length > 0
51
+ ? resolve(entry)
52
+ : entry,
53
+ ];
49
54
  return [key, resolveJsonPath(entry, tail)];
50
55
  });
51
56
  return Object.fromEntries(entries);
@@ -3,8 +3,11 @@ import { isAbsolute } from "node:path";
3
3
  import { ConfigurationError } from "../domain/configurationErrors.js";
4
4
  import { err, ok } from "../domain/result.js";
5
5
  import { analysisProviderSelectorSchema } from "../contracts/providerSelection.js";
6
+ import { ghidraStartupTimeoutSchema } from "./ghidraStartupTimeout.js";
7
+ import { mcpResponseBudgetSchema } from "./mcpResponseBudget.js";
6
8
  const environmentSchema = z.object({
7
9
  REA_ANALYSIS_PROVIDER: analysisProviderSelectorSchema.default("auto"),
10
+ REA_MCP_MAX_RESPONSE_BYTES: mcpResponseBudgetSchema.optional(),
8
11
  REA_IDA_MCP_CONFIG: z
9
12
  .string()
10
13
  .min(1)
@@ -25,6 +28,7 @@ const environmentSchema = z.object({
25
28
  .min(1)
26
29
  .refine(isAbsolute, "REA_GHIDRA_NATIVEAOT_JAR must be absolute")
27
30
  .optional(),
31
+ REA_GHIDRA_STARTUP_TIMEOUT_MS: ghidraStartupTimeoutSchema,
28
32
  REA_ILSPY_CMD_PATH: z
29
33
  .string()
30
34
  .min(1)
@@ -0,0 +1,17 @@
1
+ import { z } from "zod";
2
+ /** Default absolute deadline for Ghidra import, analysis, bridge, and readiness. */
3
+ export const DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS = 330_000;
4
+ // Node schedules delays above this signed 32-bit boundary as a 1 ms timer.
5
+ const MAX_TIMER_DELAY_MS = 2_147_483_647;
6
+ /** Parse the optional setting without reading the ambient process environment. */
7
+ export const ghidraStartupTimeoutSchema = z
8
+ .string()
9
+ .optional()
10
+ .transform((raw) => {
11
+ const value = Number(raw);
12
+ return Number.isSafeInteger(value) &&
13
+ value > 0 &&
14
+ value <= MAX_TIMER_DELAY_MS
15
+ ? value
16
+ : DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS;
17
+ });
@@ -0,0 +1,22 @@
1
+ import { z } from "zod";
2
+ import { ConfigurationError } from "../domain/configurationErrors.js";
3
+ import { err, ok } from "../domain/result.js";
4
+ // This override supports clients with larger frames. Keep the configuration
5
+ // parser independent of the SDK's eager server imports; conformance verifies
6
+ // this floor against the pinned SDK's actual default receive-buffer size.
7
+ const MINIMUM_RESPONSE_BYTES = 10 * 1024 * 1024;
8
+ /** Optional stdio response budget, including room for the protocol envelope. */
9
+ export const mcpResponseBudgetSchema = z
10
+ .string()
11
+ .regex(/^[1-9]\d*$/u)
12
+ .transform(Number)
13
+ .pipe(z.number().int().safe().min(MINIMUM_RESPONSE_BYTES));
14
+ /** Parse only the MCP-specific budget without loading unrelated provider settings. */
15
+ export const parseMcpResponseBudget = (value) => {
16
+ if (value === undefined)
17
+ return ok(undefined);
18
+ const parsed = mcpResponseBudgetSchema.safeParse(value);
19
+ return parsed.success
20
+ ? ok(parsed.data)
21
+ : err(new ConfigurationError(`REA_MCP_MAX_RESPONSE_BYTES must be a decimal safe integer at least ${String(MINIMUM_RESPONSE_BYTES)} bytes, the default stdio receive-buffer size.`));
22
+ };
@@ -16,7 +16,7 @@ const executableAvailable = (path) => {
16
16
  return false;
17
17
  }
18
18
  };
19
- export const defaultHopperLauncherPath = (platform = process.platform, homeDirectory = homedir(), executable = executableAvailable) => {
19
+ const defaultHopperLauncherPath = (platform = process.platform, homeDirectory = homedir(), executable = executableAvailable) => {
20
20
  if (platform !== "linux")
21
21
  return DEFAULT_HOPPER_LAUNCHER_PATH;
22
22
  if (executable(SYSTEM_LINUX_HOPPER))
@@ -43,6 +43,7 @@ export const parseConfig = (environment) => {
43
43
  : { idaMcpConfigPath: env.REA_IDA_MCP_CONFIG }),
44
44
  ghidraInstallDir: env.GHIDRA_INSTALL_DIR,
45
45
  ghidraJavaHome: env.JAVA_HOME,
46
+ ghidraStartupTimeoutMs: env.REA_GHIDRA_STARTUP_TIMEOUT_MS,
46
47
  ...(env.REA_GHIDRA_NATIVEAOT_JAR === undefined
47
48
  ? {}
48
49
  : { ghidraNativeAotJar: env.REA_GHIDRA_NATIVEAOT_JAR }),
@@ -18,7 +18,9 @@ export const enhancedInputSchemas = {
18
18
  .default([]),
19
19
  }),
20
20
  get_call_graph: z.strictObject({
21
- address: z.string().describe("A provider-normalized procedure address"),
21
+ address: z
22
+ .string()
23
+ .describe("A procedure symbol or address to resolve to its canonical entry"),
22
24
  direction: z.enum(["forward", "backward"]).default("forward"),
23
25
  }),
24
26
  analyze_swift_types: z.strictObject({
@@ -41,10 +43,10 @@ export const enhancedInputSchemas = {
41
43
  }),
42
44
  trace_feature: traceLiteralInputSchema,
43
45
  trace_call_path: z.strictObject({
44
- start: z.string().describe("A provider-normalized procedure address"),
46
+ start: z.string().describe("A starting procedure symbol or address"),
45
47
  goal: z
46
48
  .string()
47
- .describe("An optional provider-normalized destination address")
49
+ .describe("An optional destination procedure symbol or address")
48
50
  .optional(),
49
51
  direction: z.enum(["forward", "backward"]).default("forward"),
50
52
  }),
@@ -19,13 +19,13 @@ export const ENHANCED_TOOL_CONTRACTS = [
19
19
  enhanced("get_objc_classes", "Discover and deduplicate Objective-C class labels, optionally filtering by literal substring.", enhancedInputSchemas.get_objc_classes),
20
20
  enhanced("get_objc_protocols", "Discover and deduplicate Objective-C and Swift protocol labels.", enhancedInputSchemas.get_objc_protocols),
21
21
  enhanced("batch_decompile", "Decompile each explicit procedure symbol or address concurrently. Returns ordered per-item success or error results and aggregate counts.", enhancedInputSchemas.batch_decompile),
22
- enhanced("get_call_graph", "Traverse the bound provider's caller or callee relationships from one symbol or address until the reachable graph is exhausted. Every node has an ok/error status and failures use safe typed projections; unresolved indirect calls may be missing and results are not a whole-program CFG.", enhancedInputSchemas.get_call_graph),
22
+ enhanced("get_call_graph", "Resolve one symbol or address to its canonical procedure entry, then traverse the bound provider's caller or callee relationships until the reachable graph is exhausted. Every node uses a canonical address and has an ok/error status; failures use safe typed projections. Unresolved indirect calls may be missing and results are not a whole-program CFG.", enhancedInputSchemas.get_call_graph),
23
23
  enhanced("analyze_swift_types", 'Categorize analyzed procedure names into Swift classes, structs, enums, protocols, extensions, and other symbols. Returns deduplicated names grouped with counts. Optionally select one category and/or apply a case-sensitive literal name filter; for example, use {category: "classes", pattern: "Account"} to find matching class symbols.', enhancedInputSchemas.analyze_swift_types),
24
24
  enhanced("find_xrefs_to_name", "Resolve an exact name against the bound provider's name inventory and return a resolved or unresolved result. Unresolved names use the stable name_not_found reason; this xref workflow returns address-only projections.", enhancedInputSchemas.find_xrefs_to_name),
25
25
  enhanced("binary_overview", "Return native-binary metadata, every segment with its length, and exhaustive procedure/string counts. Use search_procedures, list_procedures, or analyze_function directly when you already know which procedure to inspect.", enhancedInputSchemas.binary_overview),
26
26
  ...FUNCTION_WORKFLOW_TOOL_CONTRACTS,
27
- enhanced("trace_feature", "Trace a literal feature query through every matching string and procedure, their xrefs, and truthful containing-procedure resolution. Returns observations, operation count, and residual unknowns without inferring reference kinds.", enhancedInputSchemas.trace_feature),
28
- enhanced("trace_call_path", "Trace direct callers or callees from one exact procedure address until the graph is exhausted or the optional goal is reached. Returns visited nodes, direct-call edges, a shortest traversal path, provider failures, and residual unknowns; unresolved indirect calls remain unknown.", enhancedInputSchemas.trace_call_path),
27
+ enhanced("trace_feature", "Trace the complete literal query, preserving spaces, through every matching string and procedure, their xrefs, and truthful containing-procedure resolution. Returns observations, operation count, and residual unknowns without inferring reference kinds.", enhancedInputSchemas.trace_feature),
28
+ enhanced("trace_call_path", "Resolve start and optional goal symbols or addresses to canonical procedure entries, then trace direct callers or callees until the graph is exhausted or the goal is reached. Results use canonical addresses; Evidence preserves supplied selectors. Returns visited nodes, direct-call edges, a shortest traversal path, provider failures, and residual unknowns; unresolved indirect calls remain unknown.", enhancedInputSchemas.trace_call_path),
29
29
  enhanced("trace_native_ui_action", "Trace one unique compiled UI action, object ID, native symbol or exact function address through authored connections, encoded or symbolized Objective-C handlers, and bounded static call references. Typed direct and resolved indirect calls, ambiguous candidates, inferred untyped provider callees, and targetless sites remain distinct. Runtime reachability is unknown; use trace_native_values for recovered value dependencies.", enhancedInputSchemas.trace_native_ui_action),
30
30
  enhanced("trace_native_values", "Trace a bounded static dependency graph from one explicit native procedure. Includes high-p-code def-use, constants, operators, memory and branch operations, resolved call edges, and derived argument/parameter and return/output bindings. Missing bindings, alias semantics, persistent state and RNG roles remain unknown. Budgets bound depth, decompilations, graph size and payloads; nodes are paginated.", enhancedInputSchemas.trace_native_values),
31
31
  ];
@@ -1,8 +1,5 @@
1
1
  import { z } from "zod";
2
- const document = z.string().optional().describe("The document name");
3
- const address = z
4
- .string()
5
- .describe("A provider-normalized address; default memory uses 0x-prefixed hexadecimal");
2
+ import { address, document } from "./toolContractHelpers.js";
6
3
  /** Hopper memory and file-mapping contracts. */
7
4
  export const HOPPER_MEMORY_TOOL_DEFINITIONS = [
8
5
  {
@@ -16,7 +13,7 @@ export const HOPPER_MEMORY_TOOL_DEFINITIONS = [
16
13
  },
17
14
  {
18
15
  name: "address_to_file_offset",
19
- description: "Map one provider-normalized virtual address to its original nonnegative file offset. Unmapped addresses fail explicitly, and providers without an authoritative mapping API return typed capability unavailability.",
16
+ description: "Map one provider-normalized virtual address to its original nonnegative file offset. Hopper verifies the original bytes against the selected executable digest and translates FAT image-relative offsets using the loaded header. Results preserve the provider coordinate, image base, and source path. Unmapped addresses fail explicitly; changed or unavailable sources return typed errors retaining native mapping facts as partial evidence.",
20
17
  inputSchema: z.object({ address, document }),
21
18
  },
22
19
  ];
@@ -85,7 +85,7 @@ export const ELECTRON_TOOL_CONTRACTS = [
85
85
  {
86
86
  name: "capture_electron_scenario",
87
87
  ...toolContractMetadata("capture_electron_scenario"),
88
- description: "Use this for a provider-owned Electron run when passive CDP or Inspector observation cannot exercise application behavior. REA owns startup and teardown, accepts caller-defined click/wait actions plus window-targeted renderer reload/crash and synthetic open-url/second-instance delivery, and returns correlated window/WebContents/process/preload/session/navigation/shell/IPC evidence without retaining payload values. Results identify observed and unavailable event families, coverage status, action targets, and truncation. External shell, navigation, permission, download, popup, updater, and OS-integration effects are blocked and recorded. Use passive Electron tools for observation-only work.",
88
+ description: "Use this for a provider-owned Electron run when passive CDP or Inspector observation cannot exercise application behavior. REA owns startup and teardown, accepts caller-defined click/wait actions plus window-targeted renderer reload/crash and synthetic open-url/second-instance delivery, and returns correlated window/WebContents/process/preload/session/navigation/shell/IPC evidence without retaining payload values. Actions wait for completion or request cancellation; a missing click target can keep the request pending. Results identify observed and unavailable event families, coverage status, action targets, and truncation. Cleanup failures retain collected observations with explicit cleanup uncertainty. External shell, navigation, permission, download, popup, updater, and OS-integration effects are blocked and recorded. Use passive Electron tools for observation-only work.",
89
89
  kind: "electron-provider",
90
90
  inputSchema: electronActiveObservationInputSchema,
91
91
  outputSchema: evidenceResultOf(electronActiveObservationResultSchema),
@@ -2,12 +2,10 @@ import { z } from "zod";
2
2
  import { managedOutputSchemas } from "../toolOutputSchemas.js";
3
3
  import { toolContractMetadata } from "../toolEffects.js";
4
4
  import { requireOutputSchema } from "../toolOutputSchemaPrimitives.js";
5
- import { isAbsoluteLocalPath } from "../../domain/localPath.js";
5
+ import { isAbsoluteLocalPath, localPathStringSchema, } from "../../domain/localPath.js";
6
6
  /** Exact caller boundary for execution-free PE/CLI triage and identity. */
7
7
  const managedTargetInputSchema = z.strictObject({
8
- path: z
9
- .string()
10
- .min(1)
8
+ path: localPathStringSchema
11
9
  .refine(isAbsoluteLocalPath, {
12
10
  message: "path must be an absolute local filesystem path (for example /tmp/Example.dll or C:\\Example.dll)",
13
11
  })
@@ -3,6 +3,7 @@ import { nativeCallObservationInputSchema } from "../../domain/native/nativeCall
3
3
  import { nativeUiObservationInputSchema, nativeUiScenarioInputSchema, } from "../../domain/native/nativeUiObservation.js";
4
4
  import { nativeOutputSchemas } from "../toolOutputSchemas.js";
5
5
  import { jsonValueSchema } from "../../domain/jsonValue.js";
6
+ import { localPathStringSchema } from "../../domain/localPath.js";
6
7
  import { toolContractMetadata } from "../toolEffects.js";
7
8
  import { requireOutputSchema } from "../toolOutputSchemaPrimitives.js";
8
9
  const examples = {
@@ -56,7 +57,8 @@ export const swiftSymbolsSchema = z
56
57
  .array(z
57
58
  .string()
58
59
  .min(1)
59
- .regex(/^[^\n]*$/u, "Each Swift symbol must be one line."))
60
+ .regex(/^[^\n]*$/u, "Each Swift symbol must be one line.")
61
+ .regex(/^[^\0]*$/u, "Swift symbols cannot contain NUL."))
60
62
  .min(1);
61
63
  /** Provider-neutral semantic operations backed initially by macOS utilities. */
62
64
  export const NATIVE_TOOL_CONTRACTS = [
@@ -66,7 +68,7 @@ export const NATIVE_TOOL_CONTRACTS = [
66
68
  native("inspect_macho", "Inspect Mach-O slices, load commands, imports, exports, dependencies, build metadata, segments, sections, permissions, and exact command provenance without launching Hopper.", z.object({})),
67
69
  native("inspect_signature", "Inspect the active artifact's code-signing identity, hashes, authorities, requirements, entitlements, hardened-runtime state, and exact command provenance.", z.object({})),
68
70
  native("inspect_plist", "Parse Info.plist from the active artifact by default, or pass any local plist path. Returns normalized JSON rather than plutil text.", z.object({
69
- path: z.string().min(1).optional(),
71
+ path: localPathStringSchema.optional(),
70
72
  })),
71
73
  native("list_architectures", "List thin or universal Mach-O slices with offsets, sizes, alignment, explicit coverage, and native-tool provenance.", z.object({})),
72
74
  native("demangle_swift", "Demangle an ordered list of single-line Swift symbols without requiring Hopper. Each input returns demangled, unchanged, or invalid status.", z.object({
@@ -32,38 +32,37 @@ export const OFFICIAL_TOOL_CONTRACTS = [
32
32
  official("current_address", "Return Hopper's current cursor address for the selected document. Use only for interactive navigation state; prefer explicit addresses in reproducible investigations.", z.object({ document })),
33
33
  official("current_procedure", "Return the analyzed procedure containing Hopper's current cursor. This uses GUI cursor state and is not a procedure-name lookup.", z.object({ document })),
34
34
  official("current_document", "Return the document currently selected by REA's Hopper bridge.", z.object({})),
35
- official("goto_address", "Move Hopper's GUI cursor to a hexadecimal address and return the resolved address. This changes navigation state but not analysis data; use explicit-address tools for headless workflows.", z.object({ address, document })),
35
+ official("goto_address", "Move Hopper's GUI cursor to a mapped address and return the observed cursor address. Interior coordinates snap to the containing analyzed object's start. Unmapped destinations fail without moving the cursor. This changes navigation state but not analysis data; use explicit-address tools for headless workflows.", z.object({ address, document })),
36
36
  official("inline_comment", "Read the inline instruction comment at an address, defaulting to the current cursor. Returns null when absent; use set_inline_comment to write one.", z.object({ document, address: optionalAddress })),
37
- official("list_bookmarks", "List every bookmark in the selected Hopper document as address and name pairs. Use bookmarks as analyst-authored navigation aids; this does not discover code references.", z.object({ document })),
37
+ official("list_bookmarks", "List every bookmark in the selected Hopper document as address and name pairs; unnamed bookmarks retain a null name. Use bookmarks as analyst-authored navigation aids; this does not discover code references.", z.object({ document })),
38
38
  official("list_documents", "List provider program or document identities. Hopper may expose several documents; a Ghidra headless session contains exactly its one imported Program.", z.object({})),
39
39
  official("list_names", "List every analyzed memory and external symbol as address/value pairs. Provider metadata distinguishes Ghidra primary, dynamic, external, type, and source facts when available.", z.object({ document, address: optionalAddress })),
40
40
  official("list_procedures", "List every analyzed procedure as address/value pairs after provider analysis. Ghidra metadata distinguishes thunks and external functions; use returned addresses in later function operations.", z.object({ document })),
41
41
  official("list_segments", "List segments or memory blocks using exclusive end addresses. Ghidra reports block permissions, address space, image base, initialization, and overlay facts; Hopper marks unavailable permissions explicitly.", z.object({ document })),
42
- official("list_strings", "List every provider-defined string, or filter to one address, as address/value pairs. Ghidra also reports encoding, terminator status, and byte length.", z.object({ document, address: optionalAddress })),
42
+ official("list_strings", "List every provider-defined string object, or filter to one address, as address/value pairs with encoding, terminator status, and byte length when available. Hopper reads complete typed objects and retains its original display text as provider_value; long literals may span adjacent unterminated objects.", z.object({ document, address: optionalAddress })),
43
43
  official("next_address", "Return the next analyzed object address after an explicit address or current cursor. This is a navigation primitive, not instruction-flow or CFG analysis.", z.object({ document, address: optionalAddress })),
44
- official("prev_address", "Return the previous analyzed instruction start before an explicit address or current cursor. This is a navigation primitive and may fail at document boundaries.", z.object({ document, address: optionalAddress })),
44
+ official("prev_address", "Return the previous analyzed object start before an explicit address or current cursor. This is a navigation primitive and may fail at document boundaries; data objects and instructions remain distinct from control flow.", z.object({ document, address: optionalAddress })),
45
45
  official("procedure_address", "Resolve an unambiguous procedure symbol name or provider-normalized address to its canonical entry address. External address spaces remain explicit.", z.object({ procedure, document })),
46
46
  official("procedure_assembly", "Return assembly for one analyzed procedure identified by symbol or hexadecimal address. Use when pseudocode loses calling-convention or instruction-level detail; output is currently returned as one unpaginated string.", z.object({ procedure, document })),
47
47
  official("procedure_callees", "Return the provider's resolved direct callees for one procedure identified by symbol or address. Unresolved indirect calls may be absent; use analyze_function and typed references to preserve available edge uncertainty.", z.object({ procedure, document })),
48
48
  official("procedure_callers", "Return the provider's resolved direct callers for one procedure identified by symbol or address. Results reflect completed static analysis and may omit unresolved indirect references.", z.object({ procedure, document })),
49
- official("procedure_info", "Return provider metadata for one procedure identified by symbol or address: entrypoint, signature, locals, size, block count, and complete inclusive body ranges when observed. Body byte count and enclosing span remain distinct; unavailable extent is explicit.", z.object({ procedure, document })),
49
+ official("procedure_info", "Return provider metadata for one procedure identified by symbol or address: entrypoint, signature, locals, size, block count, and complete inclusive body ranges when observed. Hopper locals preserve observed names and signed stack displacements; source types remain unknown. Body byte count and enclosing span remain distinct; unavailable extent is explicit.", z.object({ procedure, document })),
50
50
  official("read_function_instructions", "Return every raw instruction for one analyzed procedure. Instruction text is provider-specific.", functionInstructionInputSchema),
51
51
  ...HOPPER_MEMORY_TOOL_DEFINITIONS.map(({ name, description, inputSchema }) => official(name, description, inputSchema)),
52
- official("procedure_references", "Return every raw incoming or outgoing reference edge for one procedure. Endpoint procedures are resolved only from provider containment; Ghidra preserves observed reference kinds while providers without kind authority mark them unavailable.", z.object({
52
+ official("procedure_references", "Return every raw incoming or outgoing reference edge for one procedure. Endpoint procedures are resolved only from provider containment. Ghidra preserves detailed reference flags. Hopper preserves native CallReference classifications and exact endpoints while leaving unavailable detailed flags explicit.", z.object({
53
53
  procedure,
54
54
  direction: z.enum(["incoming", "outgoing"]).default("outgoing"),
55
55
  document,
56
56
  })),
57
57
  official("procedure_pseudo_code", "Decompile one analyzed procedure by symbol name or provider-normalized address. Returns provider-specific pseudocode, never original source or cross-provider text equivalence, and may return null; request procedure_assembly when instruction precision matters.", z.object({ procedure, document })),
58
58
  official("resolve_containing_procedure", "Resolve an arbitrary address, including an interior instruction or exact external entry, to its provider-analyzed containing procedure. A negative result distinguishes outside segments from not in a procedure and is never guessed from nearby symbols.", z.object({ address, document })),
59
- official("search_procedures", "Search every analyzed procedure name using literal matching by default or regex when requested. Results are deterministic and complete.", z.object(analysisSearchInput)),
60
- official("search_strings", "Search every analyzed string using literal matching by default or regex when requested. Results are deterministic and complete.", z.object(analysisSearchInput)),
61
- official("set_address_name", "Assign an analyst name to one hexadecimal address and report Hopper's boolean result. This mutates analysis metadata.", z.object({ address, name: z.string(), document })),
62
- official("set_addresses_names", "Assign analyst names to multiple addresses in one call and return per-address success booleans. This mutates analysis metadata; verify failures individually.", z.object({ names: z.record(z.string(), z.string()), document })),
63
- official("set_bookmark", "Create or replace a bookmark at a hexadecimal address and report success. This mutates navigation metadata; bookmarks are analyst-authored navigation aids, not binary evidence.", z.object({ address, name: z.string().optional(), document })),
64
- official("set_comment", "Write a regular analysis comment at a hexadecimal address and return whether readback matched. This mutates the Hopper document; use comments to record evidence IDs or reasoning.", z.object({ address, comment: z.string(), document })),
65
- official("set_current_document", "Select an already-open Hopper document by exact document name. This changes subsequent default-document routing; list_documents can supply names when needed, while explicit document inputs keep calls reproducible.", z.object({ document: z.string() })),
66
- official("set_inline_comment", "Write an inline instruction comment at a hexadecimal address and return whether readback matched. This mutates analysis metadata.", z.object({ address, comment: z.string(), document })),
67
- official("unset_bookmark", "Remove the bookmark at a hexadecimal address and return whether it is absent. This mutates navigation metadata and does not alter binary bytes.", z.object({ address, document })),
59
+ official("search_procedures", "Search every analyzed procedure name using literal matching by default or regex when requested. Results are deterministic and complete. Hopper regex mode uses ECMAScript Unicode syntax in a cancellable worker; a matching deadline leaves its API usable.", z.object(analysisSearchInput)),
60
+ official("search_strings", "Search every analyzed string object using literal matching by default or regex when requested. Results are deterministic and complete over the native inventory. Hopper retains typed byte decoding, native display, and explicit decoding unknowns. Adjacent long-literal fragments match independently. Hopper regex mode uses ECMAScript Unicode syntax in a cancellable worker; a matching deadline leaves its API usable.", z.object(analysisSearchInput)),
61
+ official("set_address_name", "Assign an analyst name to one mapped hexadecimal address and report whether the native edit succeeded and exact readback matched. Hopper rejects symbol names exceeding 1024 UTF-16 code units before mutation, and rejects names owned by another address; use set_addresses_names to explicitly move or swap labels among selected addresses. This mutates analysis metadata.", z.object({ address, name: z.string(), document })),
62
+ official("set_addresses_names", "Assign analyst names to multiple mapped addresses in one call and return per-address edit/readback success booleans. Hopper validates mapped destinations, native string representations, its 1024 UTF-16 code-unit symbol-name limit, and unique destinations/names before applying edits. Existing labels may move or swap only among explicitly selected addresses; unselected label owners remain unchanged. This mutates analysis metadata; verify failures individually.", z.object({ names: z.record(z.string(), z.string()), document })),
63
+ official("set_bookmark", "Create or replace a bookmark at a mapped hexadecimal address and report success. This mutates navigation metadata; bookmarks are analyst-authored navigation aids, not binary evidence.", z.object({ address, name: z.string().optional(), document })),
64
+ official("set_comment", "Write a regular analysis comment at a hexadecimal address and return whether readback matched. An empty comment clears it. This mutates the Hopper document; use comments to record evidence IDs or reasoning.", z.object({ address, comment: z.string(), document })),
65
+ official("set_inline_comment", "Write an inline instruction comment at a hexadecimal address and return whether readback matched. An empty comment clears it; Hopper may flatten newlines, producing false on exact readback. This mutates analysis metadata.", z.object({ address, comment: z.string(), document })),
66
+ official("unset_bookmark", "Remove the bookmark at a mapped hexadecimal address and return whether it is absent. Hopper also permits removing an existing legacy bookmark outside mapped memory. This mutates navigation metadata and does not alter binary bytes.", z.object({ address, document })),
68
67
  official("xrefs", "Return analyzed references to a code or data address. Hopper may default to its current cursor; headless providers such as Ghidra require an explicit address. Use to connect strings, globals, selectors, and functions; bare addresses are untyped and indirect references may be incomplete.", z.object({ document, address: optionalAddress })),
69
68
  ];
@@ -46,7 +46,7 @@ export const PROMPT_CONTRACTS = [
46
46
  arguments: {
47
47
  feature: required("Feature, behavior, string, or symbol to investigate"),
48
48
  target_path: optional("Absolute target path; omit when the intended target is already open"),
49
- document: optional("Open Hopper document to inspect", "document"),
49
+ document: optional("Active target's provider document name", "document"),
50
50
  procedure: optional("Known procedure name or address to prioritize", "procedure"),
51
51
  provider_id: optional("Configured provider identity to prefer when its capability is available", "provider"),
52
52
  },
@@ -56,8 +56,8 @@ export const PROMPT_CONTRACTS = [
56
56
  instruction: "For a JavaScript/Electron application directory, call analyze_javascript_application with input_path=target_path directly; no open_binary call is needed. For a file or macOS app bundle, open target_path only when the required target is not active.",
57
57
  },
58
58
  {
59
- tools: ["list_documents", "set_current_document"],
60
- instruction: "Select a document only when needed for the requested analysis.",
59
+ tools: ["current_document"],
60
+ instruction: "Analysis stays bound to the active target's provider document. Use open_binary to switch targets; document names never select another artifact.",
61
61
  },
62
62
  {
63
63
  tools: ["search_strings", "search_procedures", "procedure_address"],
@@ -1,19 +1,15 @@
1
1
  import { executableFormatHintSchema } from "../domain/dosCom.js";
2
- import { isAbsoluteLocalPath } from "../domain/localPath.js";
2
+ import { isAbsoluteLocalPath, localPathStringSchema, } from "../domain/localPath.js";
3
3
  import { z } from "zod";
4
4
  import { analysisProviderSelectorSchema } from "./providerSelection.js";
5
5
  /** Caller-supplied analysis snapshot path; must name its destination absolutely. */
6
- const snapshotPathSchema = z
7
- .string()
8
- .min(1)
6
+ const snapshotPathSchema = localPathStringSchema
9
7
  .refine(isAbsoluteLocalPath, {
10
8
  message: "snapshot_path must be an absolute local filesystem path (for example /tmp/rea/analysis.json or C:\\rea\\analysis.json)",
11
9
  })
12
10
  .describe("Absolute local filesystem path for the analysis snapshot; relative paths are rejected.");
13
11
  /** Caller-supplied analysis target path; must name the target absolutely. */
14
- const binaryTargetPathSchema = z
15
- .string()
16
- .min(1)
12
+ const binaryTargetPathSchema = localPathStringSchema
17
13
  .refine(isAbsoluteLocalPath, {
18
14
  message: "path must be an absolute local filesystem path (for example /tmp/fixture.bin or C:\\analysis\\fixture.bin)",
19
15
  })
@@ -1,5 +1,5 @@
1
1
  import { z } from "zod";
2
- import { isAbsoluteLocalPath } from "../domain/localPath.js";
2
+ import { isAbsoluteLocalPath, localPathStringSchema, } from "../domain/localPath.js";
3
3
  /** Optional expectations used to compare the live session with its caller. */
4
4
  export const binarySessionInputSchema = z.strictObject({
5
5
  expected_package_version: z.string().min(1).optional(),
@@ -7,9 +7,7 @@ export const binarySessionInputSchema = z.strictObject({
7
7
  .string()
8
8
  .regex(/^[a-f0-9]{64}$/u)
9
9
  .optional(),
10
- expected_server_path: z
11
- .string()
12
- .min(1)
10
+ expected_server_path: localPathStringSchema
13
11
  .refine(isAbsoluteLocalPath, {
14
12
  message: "expected_server_path must be an absolute local filesystem path (for example /opt/rea/dist/main.js)",
15
13
  })
@@ -1,5 +1,5 @@
1
1
  import { z } from "zod";
2
- import { isAbsoluteLocalPath } from "../domain/localPath.js";
2
+ import { isAbsoluteLocalPath, localPathStringSchema, } from "../domain/localPath.js";
3
3
  import { sessionOutputSchemas, requireOutputSchema, } from "./toolOutputSchemas.js";
4
4
  import { addressContextInputSchema, artifactComparisonInputSchema, binarySessionInputSchema, bundleComparisonInputSchema, callPathInputSchema, changedBehaviorInputSchema, closeBinaryInputSchema, functionComparisonInputSchema, importEvidenceBundleInputSchema, listUnknownsInputSchema, navigationContextInputSchema, openBinaryInputSchema, processComparisonInputSchema, processScenarioSchema, reconstructionVerificationInputSchema, recordUnknownInputSchema, getEvidenceBundleInputSchema, staticRuntimeCorrelationInputSchema, updateUnknownInputSchema, verifyUnknownResolutionInputSchema, } from "./sessionToolSchemas.js";
5
5
  import { examplesFor } from "./toolContractHelpers.js";
@@ -15,9 +15,7 @@ const session = (name, description, inputSchema) => ({
15
15
  });
16
16
  /** Session-owned Evidence bundle export options. */
17
17
  export const exportEvidenceBundleInputSchema = z.strictObject({
18
- path: z
19
- .string()
20
- .min(1)
18
+ path: localPathStringSchema
21
19
  .refine(isAbsoluteLocalPath, {
22
20
  message: "path must be an absolute local filesystem path (for example /tmp/rea/evidence.json or C:\\rea\\evidence.json)",
23
21
  })
@@ -26,8 +24,8 @@ export const exportEvidenceBundleInputSchema = z.strictObject({
26
24
  });
27
25
  /** Target lifecycle tools available only on the long-lived MCP adapter. */
28
26
  export const SESSION_TOOL_CONTRACTS = [
29
- session("open_binary", "Open a local executable, application bundle, archive, JavaScript, source map, plist, or analysis database after validation. format=dos-com explicitly interprets 1..65280 headerless bytes as a DOS COM analysis image; omission preserves header-based detection. provider_id selects one deep provider or deterministic auto selection; the binding remains stable until close or an explicit switch, with no failure fallback. An optional analysis snapshot is imported atomically and must match the binary identity, concrete provider, and canonical analysis profile exactly.", openBinaryInputSchema),
30
- session("close_binary", "Optionally write a provider-neutral analysis snapshot atomically to the caller-supplied path, then close the active target and every provider resource started for it. Existing files require explicit overwrite; a failed save leaves the session open so cached analysis is not lost.", closeBinaryInputSchema),
27
+ session("open_binary", "Open a local executable, application bundle, archive, JavaScript, source map, plist, or analysis database after validation. format=dos-com explicitly interprets 1..65280 headerless bytes as a DOS COM analysis image; omission preserves header-based detection. provider_id selects one deep provider or deterministic auto selection; the binding remains stable until close or an explicit switch, with no failure fallback. Reopening the same target and profile retains its active database and metadata edits. An optional analysis snapshot is imported atomically and must match the binary identity, concrete provider, and canonical analysis profile exactly; importing into a session with metadata mutations requires closing and reopening it first.", openBinaryInputSchema),
28
+ session("close_binary", "Drain earlier provider requests, optionally write a provider-neutral analysis snapshot atomically to the caller-supplied path, then close the active target and every provider resource started for it. Later provider requests wait until this lifecycle operation finishes. Existing files require explicit overwrite; a failed save leaves the session open so cached analysis is not lost. Metadata edits prevent immutable snapshot saves until the session is recreated; export_evidence_bundle preserves mutable observations before closing without a snapshot.", closeBinaryInputSchema),
31
29
  session("binary_session", "Report the complete current target, provider, capability availability, client-feature, analysis, and server-identity status without starting analysis.", binarySessionInputSchema),
32
30
  session("export_evidence_bundle", "Atomically write the session's deterministic Evidence bundle to the requested local path. Existing files require overwrite: true; records and manifests use canonical byte-stable ordering.", exportEvidenceBundleInputSchema),
33
31
  session("import_evidence_bundle", "Read the JSON bundle at the supplied local path, validate every Evidence ID and canonical manifest, then atomically merge it. Imported content is data only and is never executed.", importEvidenceBundleInputSchema),
@@ -1,11 +1,10 @@
1
1
  import { z } from "zod";
2
- import { isAbsoluteLocalPath } from "../domain/localPath.js";
2
+ import { isAbsoluteLocalPath, localPathStringSchema, } from "../domain/localPath.js";
3
3
  import { artifactComparisonInputSchema } from "../domain/artifactComparison.js";
4
4
  import { bundleComparisonInputSchema } from "../domain/bundleComparison.js";
5
5
  import { callPathInputSchema } from "../domain/callPath.js";
6
6
  import { changedBehaviorInputSchema } from "../domain/changedBehavior.js";
7
7
  import { functionComparisonInputSchema } from "../domain/functionComparison.js";
8
- import { jsonValueSchema } from "../domain/jsonValue.js";
9
8
  import { processScenarioSchema } from "../domain/process/processCapture.js";
10
9
  import { processTraceSpecificationSchema } from "../domain/process/processTraceComparison.js";
11
10
  import { recordUnknownInputSchema } from "../domain/residualUnknown.js";
@@ -29,9 +28,7 @@ export const addressContextInputSchema = z.strictObject({
29
28
  });
30
29
  /** Session-owned Evidence bundle import options. */
31
30
  export const importEvidenceBundleInputSchema = z.strictObject({
32
- path: z
33
- .string()
34
- .min(1)
31
+ path: localPathStringSchema
35
32
  .refine(isAbsoluteLocalPath, {
36
33
  message: "path must be an absolute local filesystem path (for example /tmp/evidence.json or C:\\rea\\evidence.json)",
37
34
  })
@@ -28,7 +28,6 @@ export const TOOL_EXAMPLE_OVERRIDES = {
28
28
  set_addresses_names: { names: { "0x1000": "entry" } },
29
29
  set_bookmark: { address: "0x1000" },
30
30
  set_comment: { address: "0x1000", comment: "validated entry point" },
31
- set_current_document: { document: "fixture" },
32
31
  set_inline_comment: { address: "0x1000", comment: "calls parser" },
33
32
  unset_bookmark: { address: "0x1000" },
34
33
  get_call_graph: { address: "0x1000" },
@@ -1,7 +1,10 @@
1
1
  import { z } from "zod";
2
2
  import { jsonValueSchema } from "../domain/jsonValue.js";
3
3
  import { TOOL_EXAMPLE_OVERRIDES } from "./toolContractExamples.js";
4
- export const document = z.string().optional().describe("The document name");
4
+ export const document = z
5
+ .string()
6
+ .optional()
7
+ .describe("The active target's provider document name; use open_binary to switch targets");
5
8
  export const address = z
6
9
  .string()
7
10
  .describe("A provider-normalized address; default memory uses 0x-prefixed hexadecimal");
@@ -138,7 +138,6 @@ export const TOOL_EFFECTS = {
138
138
  set_addresses_names: effects({ mutatesTarget: true, mutatesSession: true }),
139
139
  set_bookmark: effects({ mutatesTarget: true, mutatesSession: true }),
140
140
  set_comment: effects({ mutatesTarget: true, mutatesSession: true }),
141
- set_current_document: effects({ mutatesSession: true, changesUiState: true }),
142
141
  set_inline_comment: effects({ mutatesTarget: true, mutatesSession: true }),
143
142
  unset_bookmark: effects({
144
143
  mutatesTarget: true,
@@ -10,7 +10,7 @@ import { jsonValueSchema } from "../domain/jsonValue.js";
10
10
  import { residualUnknownSchema } from "../domain/residualUnknown.js";
11
11
  import { evidenceBundleSchema } from "../domain/evidenceBundle.js";
12
12
  import { processCaptureComparisonSchema, processCaptureSchema, } from "../domain/process/processCapture.js";
13
- import { functionInstructionWindowSchema, referenceKindSchema, } from "../domain/hopperValues.js";
13
+ import { analysisBookmarkSchema, functionInstructionWindowSchema, referenceEdgeSchema, unresolvedCallSchema, analysisStringSchema, } from "../domain/hopperValues.js";
14
14
  import { nativeApiInspectionResultSchema } from "../domain/native/nativeApiBoundary.js";
15
15
  import { demangleSwiftSchema, inspectMachoSchema, inspectPlistSchema, inspectSignatureSchema, listArchitecturesSchema, } from "../domain/native/nativeInspection.js";
16
16
  import { artifactExtractionResultSchema } from "../domain/artifactGraph.js";
@@ -44,24 +44,16 @@ const contextFacetSchema = z.discriminatedUnion("state", [
44
44
  }),
45
45
  ]);
46
46
  const bookmarkFacetSchema = z.discriminatedUnion("state", [
47
- z.object({ state: z.literal("available"), value: z.array(addressedEntry) }),
47
+ z.object({
48
+ state: z.literal("available"),
49
+ value: z.array(analysisBookmarkSchema),
50
+ }),
48
51
  z.object({
49
52
  state: z.literal("unavailable"),
50
53
  reason: z.string(),
51
54
  remediation: z.string(),
52
55
  }),
53
56
  ]);
54
- const addressedString = z.object({
55
- address: z.string(),
56
- value: z.string(),
57
- string: z
58
- .object({
59
- encoding: z.string().min(1),
60
- termination: z.enum(["missing", "present_or_not_required"]),
61
- byte_length: z.number().int().min(0),
62
- })
63
- .optional(),
64
- });
65
57
  /** Exact structured-content schemas shared by direct analysis providers. */
66
58
  export const officialOutputSchemas = {
67
59
  annotate_native_function: resultOf(nativeFunctionAnnotationsSchema),
@@ -76,12 +68,12 @@ export const officialOutputSchemas = {
76
68
  current_document: resultOf(z.string()),
77
69
  goto_address: resultOf(z.string()),
78
70
  inline_comment: resultOf(nullableText),
79
- list_bookmarks: resultOf(z.array(addressedEntry)),
71
+ list_bookmarks: resultOf(z.array(analysisBookmarkSchema)),
80
72
  list_documents: resultOf(z.array(z.string())),
81
73
  list_names: resultOf(z.array(addressedValue)),
82
74
  list_procedures: resultOf(z.array(addressedValue)),
83
75
  list_segments: segmentOutput,
84
- list_strings: resultOf(z.array(addressedString)),
76
+ list_strings: resultOf(z.array(analysisStringSchema)),
85
77
  next_address: resultOf(z.string()),
86
78
  prev_address: resultOf(z.string()),
87
79
  procedure_address: resultOf(z.string()),
@@ -100,31 +92,40 @@ export const officialOutputSchemas = {
100
92
  address_to_file_offset: resultOf(z.object({
101
93
  address: z.string(),
102
94
  file_offset: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
95
+ provider_file_offset: z
96
+ .number()
97
+ .int()
98
+ .min(0)
99
+ .max(Number.MAX_SAFE_INTEGER)
100
+ .exactOptional()
101
+ .describe("Original coordinate returned by the provider's mapping API."),
102
+ image_base_file_offset: z
103
+ .number()
104
+ .int()
105
+ .min(0)
106
+ .max(Number.MAX_SAFE_INTEGER)
107
+ .exactOptional()
108
+ .describe("File offset of the loaded image within its source container; zero for a thin executable."),
109
+ source_path: z
110
+ .string()
111
+ .exactOptional()
112
+ .describe("Observed original executable path used to verify the file mapping."),
103
113
  })),
104
114
  procedure_references: resultOf(z.object({
105
115
  procedure: procedureIdentity,
106
116
  direction: z.enum(["incoming", "outgoing"]),
107
117
  reference_kinds_available: z.boolean().optional(),
108
- unresolved_calls: z
109
- .array(z.object({ address: z.string(), reason: z.string() }))
110
- .default([]),
111
- references: z.array(z.object({
112
- source_address: z.string(),
113
- target_address: z.string(),
114
- source_procedure: procedureIdentity.nullable(),
115
- target_procedure: procedureIdentity.nullable(),
116
- kind: referenceKindSchema,
117
- })),
118
+ unresolved_calls: z.array(unresolvedCallSchema).default([]),
119
+ references: z.array(referenceEdgeSchema),
118
120
  })),
119
121
  procedure_pseudo_code: resultOf(nullableText),
120
122
  resolve_containing_procedure: resultOf(containingProcedureResolution),
121
123
  search_procedures: resultOf(z.array(z.object({ address: z.string(), value: z.string() }))),
122
- search_strings: resultOf(z.array(z.object({ address: z.string(), value: z.string() }))),
124
+ search_strings: resultOf(z.array(analysisStringSchema)),
123
125
  set_address_name: resultOf(z.boolean()),
124
126
  set_addresses_names: resultOf(z.record(z.string(), z.boolean())),
125
127
  set_bookmark: resultOf(z.boolean()),
126
128
  set_comment: resultOf(z.boolean()),
127
- set_current_document: resultOf(z.string()),
128
129
  set_inline_comment: resultOf(z.boolean()),
129
130
  unset_bookmark: resultOf(z.boolean()),
130
131
  xrefs: resultOf(addressList),
@@ -4,16 +4,19 @@ import { analysisProfileSchema } from "../domain/analysisProfile.js";
4
4
  import { evidenceEnvelopeSchema } from "../domain/evidence.js";
5
5
  import { jsonValueSchema } from "../domain/jsonValue.js";
6
6
  import { PROVIDER_REJECTION_CODES, } from "./providerSelection.js";
7
+ import { PROVIDER_FAILURE_STAGES, PROVIDER_OPERATION_STATES, PROVIDER_RETRY_ACTIONS, } from "../domain/providerOperationHealth.js";
7
8
  import { analysisErrorProjectionSchema } from "./errorSchemas.js";
8
9
  import { prefixedDigestSchema } from "./../domain/digests.js";
9
10
  /** Inline result with its complete Evidence record. */
10
11
  export const inlineEvidenceRecordSchema = evidenceEnvelopeSchema;
12
+ /** Wrap a result and its Evidence while preserving the result schema type. */
11
13
  export const evidenceResultOf = (schema) => z.strictObject({
12
14
  result: schema,
13
15
  evidence_id: prefixedDigestSchema("ev"),
14
16
  evidence: inlineEvidenceRecordSchema,
15
17
  });
16
18
  const resultOf = evidenceResultOf;
19
+ /** Wrap a lifecycle result while preserving its exact schema type. */
17
20
  export const lifecycleResultOf = (schema) => z.object({ result: schema });
18
21
  /** Resolve a required named output schema or reject contract drift. */
19
22
  export const requireOutputSchema = (schemas, name) => {
@@ -133,6 +136,20 @@ export const analysisActivity = z.object({
133
136
  queued_requests: z.number().int().min(0),
134
137
  })),
135
138
  });
139
+ const providerOperationRequest = z.object({
140
+ request_id: z.number().int().min(1),
141
+ operation: z.string().min(1),
142
+ stage: z.enum(PROVIDER_FAILURE_STAGES),
143
+ });
144
+ export const providerOperationHealth = z
145
+ .object({
146
+ state: z.enum(PROVIDER_OPERATION_STATES),
147
+ stage: z.enum(PROVIDER_FAILURE_STAGES).nullable(),
148
+ retry_action: z.enum(PROVIDER_RETRY_ACTIONS).nullable(),
149
+ exit_code: z.number().int().nullable(),
150
+ requests: z.array(providerOperationRequest),
151
+ })
152
+ .nullable();
136
153
  const providerRejectionCode = z.enum(PROVIDER_REJECTION_CODES);
137
154
  const providerDiagnostics = z.record(z.string(), jsonValueSchema);
138
155
  const providerAvailability = z.discriminatedUnion("status", [
@@ -259,6 +276,7 @@ export const sessionProvider = z
259
276
  capabilities: z.array(providerCapability),
260
277
  analysis_run: analysisRun,
261
278
  analysis_activity: analysisActivity,
279
+ provider_operation_health: providerOperationHealth,
262
280
  analysis_provider_binding: z
263
281
  .object({
264
282
  provider: providerIdentity,