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
@@ -38,28 +38,87 @@ const PROPERTY_DESCRIPTIONS = {
38
38
  unknown_id: "Exact residual-unknown identifier.",
39
39
  };
40
40
  /** Attach caller guidance to a canonical schema for the SDK wire projection. */
41
- export const toolInputSchemaWithMetadata = (contract) => {
42
- const schema = contract.inputSchema.meta(z.globalRegistry.get(contract.inputSchema) ?? {});
43
- const standard = schema["~standard"];
44
- const inputJsonSchema = standard.jsonSchema?.input;
45
- if (inputJsonSchema === undefined)
46
- throw new TypeError("Tool input schema does not expose Standard JSON Schema");
41
+ export const toolInputSchemaWithMetadata = (contract) => withAdvertisedJsonSchema(contract.inputSchema, "input", (project) => (options) => flattenRootUnion({
42
+ ...describeProperties(project(options)),
43
+ examples: contract.examples.map(({ input }) => input),
44
+ }));
45
+ /** Advertise a canonical output schema without reconverting it per listing. */
46
+ export const toolOutputSchemaWithMetadata = (contract) => withAdvertisedJsonSchema(contract.outputSchema, "output");
47
+ const withAdvertisedJsonSchema = (canonical, io, advertise = (project) => project) => {
47
48
  // Zod's input projection drops root metadata when a descendant transforms.
48
49
  // Preserve the parser and let the SDK own conversion of everything else.
50
+ const schema = canonical.meta(z.globalRegistry.get(canonical) ?? {});
51
+ const standard = schema["~standard"];
52
+ const project = standard.jsonSchema?.[io];
53
+ if (project === undefined)
54
+ throw new TypeError(`Tool ${io} schema does not expose Standard JSON Schema`);
49
55
  Object.defineProperty(schema, "~standard", {
50
56
  value: {
51
57
  ...standard,
52
58
  jsonSchema: {
53
59
  ...standard.jsonSchema,
54
- input: (options) => ({
55
- ...describeProperties(inputJsonSchema(options)),
56
- examples: contract.examples.map(({ input }) => input),
57
- }),
60
+ [io]: memoizeByTarget(advertise(project)),
58
61
  },
59
62
  },
60
63
  });
61
64
  return schema;
62
65
  };
66
+ // The SDK reconverts every registered schema on each `tools/list`, although a
67
+ // registered contract cannot change. Like the SDK's own memoized output
68
+ // projection, the advertised value is shared and treated as read-only.
69
+ const memoizeByTarget = (project) => {
70
+ const byTarget = new Map();
71
+ return (options) => {
72
+ if (options.libraryOptions !== undefined)
73
+ return project(options);
74
+ const cached = byTarget.get(options.target);
75
+ if (cached !== undefined)
76
+ return cached;
77
+ const projected = project(options);
78
+ byTarget.set(options.target, projected);
79
+ return projected;
80
+ };
81
+ };
82
+ /** Keep MCP tool roots object-shaped for clients that reject root unions. */
83
+ const flattenRootUnion = (value) => {
84
+ if (!Array.isArray(value.anyOf))
85
+ return value;
86
+ const branches = value.anyOf.filter(isObject);
87
+ if (branches.length === 0 || branches.length !== value.anyOf.length)
88
+ return value;
89
+ const properties = {};
90
+ for (const branch of branches) {
91
+ if (!isObject(branch.properties))
92
+ return value;
93
+ for (const [name, schema] of Object.entries(branch.properties)) {
94
+ const previous = properties[name];
95
+ if (previous === undefined)
96
+ properties[name] = schema;
97
+ else if (JSON.stringify(previous) !== JSON.stringify(schema))
98
+ properties[name] = {
99
+ anyOf: [previous, schema],
100
+ description: fallbackPropertyDescription(name),
101
+ };
102
+ }
103
+ }
104
+ // The canonical Zod parser still enforces branch validation at invocation.
105
+ const { anyOf: _anyOf, required: _required, ...root } = value;
106
+ const requiredByBranch = branches.map((branch) => Array.isArray(branch.required)
107
+ ? branch.required.filter((item) => typeof item === "string")
108
+ : []);
109
+ const required = requiredByBranch.reduce((common, current) => common.filter((name) => current.includes(name)));
110
+ const minProperties = Math.max(typeof root.minProperties === "number" ? root.minProperties : 0, Math.min(...requiredByBranch.map((names) => names.length)));
111
+ return {
112
+ ...root,
113
+ type: "object",
114
+ properties,
115
+ ...(minProperties > 0 ? { minProperties } : {}),
116
+ ...(required.length > 0 ? { required } : {}),
117
+ ...(branches.every((branch) => branch.additionalProperties === false)
118
+ ? { additionalProperties: false }
119
+ : {}),
120
+ };
121
+ };
63
122
  const describeProperties = (value) => Object.fromEntries(Object.entries(value).map(([key, child]) => {
64
123
  if (key !== "properties" || !isObject(child))
65
124
  return [key, describeValue(child)];
@@ -6,7 +6,7 @@ export const WEB_NETWORK_CAPTURE_TOOL_CONTRACTS = [
6
6
  {
7
7
  name: "inspect_web_network_capture",
8
8
  ...toolContractMetadata("inspect_web_network_capture"),
9
- description: "Inspect retained local HAR 1.2 or native mitmproxy capture records without contacting recorded URLs. Returns original ordinals, pointers/byte ranges, preserved producer fields, precise numeric representations and exact exposed binary bytes inline. Excludes known transport credentials and explicitly marked values. Decodes every record before optional ordinal selection; malformed or oversized captures return no partial success. Duplicate HAR members are invalid; prototype-named __proto__ members are unsupported by the current shared JSON boundary. Uses pinned upstream parsers, owned temporary files and bounded offline processes. Native mitmproxy requires caller-supplied mitmdump 12.2.3 on Linux. Browser transaction IDs, runtime attribution and original bytes of HAR Unicode text remain unknown.",
9
+ description: "Inspect retained local HAR 1.2 or native mitmproxy capture records without contacting recorded URLs. Returns original ordinals, pointers/byte ranges, preserved producer fields, precise numeric representations and exact exposed binary bytes inline. Excludes known transport credentials and explicitly marked values. Decodes every record before optional ordinal selection; malformed or oversized captures return no partial success. Duplicate HAR members are invalid; prototype-named members such as __proto__ are preserved as ordinary own JSON members without prototype mutation. Uses pinned upstream parsers, owned temporary files and bounded offline processes. Native mitmproxy requires caller-supplied mitmdump 12.2.3 on Linux. Browser transaction IDs, runtime attribution and original bytes of HAR Unicode text remain unknown.",
10
10
  kind: "browser-provider",
11
11
  inputSchema: inspectWebNetworkCaptureInputSchema,
12
12
  outputSchema: evidenceResultOf(webNetworkCaptureSchema),
@@ -31,18 +31,23 @@ const ANALYSIS_ERROR_TAGS = [
31
31
  /** Base class for expected analysis, provider, and session failures. */
32
32
  export class AnalysisError extends Error {
33
33
  capturedOutput;
34
+ cleanup;
35
+ cleanupIncomplete;
36
+ cleanupResources;
34
37
  constructor(message, options) {
35
38
  super(message, options);
36
39
  this.capturedOutput =
37
40
  options?.capturedOutput === undefined
38
41
  ? undefined
39
42
  : { ...options.capturedOutput };
43
+ this.cleanup = options?.cleanup;
44
+ this.cleanupIncomplete = options?.cleanup !== undefined;
45
+ this.cleanupResources = options?.cleanup?.resources ?? [];
46
+ this.partialObservation = options?.partialObservation;
40
47
  }
41
48
  userMessage = undefined;
42
49
  userCategory = undefined;
43
- cleanupIncomplete = false;
44
- cleanupResources = [];
45
50
  executionFailure = undefined;
46
- partialObservation = undefined;
51
+ partialObservation;
47
52
  cleanupReport = undefined;
48
53
  }
@@ -12,19 +12,21 @@ export class AnalysisUnsupportedTargetError extends AnalysisError {
12
12
  this.reason = reason;
13
13
  }
14
14
  }
15
- /** Provider reported a resource failure, distinct from malformed input or unsupported coverage. */
15
+ /** An analysis or transport resource failure, distinct from malformed input or unsupported coverage. */
16
16
  export class AnalysisResourceConstraintError extends AnalysisError {
17
17
  operation;
18
18
  resource;
19
19
  reason;
20
20
  reportedLimits;
21
21
  _tag = "AnalysisResourceConstraintError";
22
+ remediationAction;
22
23
  constructor(operation, resource, reason, reportedLimits, options) {
23
24
  super(`Resource constraint during ${operation}: ${reason}`, options);
24
25
  this.operation = operation;
25
26
  this.resource = resource;
26
27
  this.reason = reason;
27
28
  this.reportedLimits = reportedLimits;
29
+ this.remediationAction = options?.remediationAction;
28
30
  }
29
31
  }
30
32
  /** Provider-neutral invalid analysis input or output at an application boundary. */
@@ -2,33 +2,43 @@ import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisInputE
2
2
  import { ArtifactOperationError } from "./artifactOperationError.js";
3
3
  import { BinaryTargetError, ConfigurationError, NoBinaryOpenError, } from "./configurationErrors.js";
4
4
  import { BrowserObservationError } from "./browserObservationError.js";
5
- import { EvidenceFileError, EvidenceIntegrityError, EvidenceReferenceError, } from "./evidenceErrors.js";
5
+ import { EvidenceFileError, EvidenceIntegrityError, EvidenceReferenceError, AnalysisSnapshotMismatchError, } from "./evidenceErrors.js";
6
6
  import { HopperRemoteError, HopperProcessError, HopperStartError, HopperTimeoutError, } from "./hopperErrors.js";
7
7
  import { ProviderSelectionError } from "./providerSelectionError.js";
8
8
  import { UnknownRegistryError } from "./unknownRegistryError.js";
9
+ import { providerRetryAction } from "./providerOperationHealth.js";
9
10
  import {} from "./analysisErrorBase.js";
10
11
  import {} from "./analysisErrorProjection.js";
11
12
  export const analysisErrorRemediationAction = (error) => {
13
+ if (error instanceof AnalysisSnapshotMismatchError)
14
+ return "Run analysis without this snapshot, then save a fresh snapshot using the intended artifact, provider, and analysis profile.";
12
15
  if (error instanceof AnalysisUnsupportedTargetError)
13
16
  return "Select a target supported by this operation or choose an operation supporting the reported target format.";
14
17
  if (error instanceof AnalysisResourceConstraintError)
15
- return error.resource === "cpu"
16
- ? "Review the reported worker CPU limits and observed signal. Retry with sufficient CPU time or a smaller artifact; REA retains tighter inherited limits."
17
- : error.resource === "file-size"
18
- ? "Review the reported worker file-size limits and write failure. Retry with a sufficient file-size allowance for the evidence reply; REA retains tighter inherited limits."
19
- : "Review the reported worker memory limits and available host memory. Retry with sufficient memory or a smaller artifact; REA retains tighter inherited limits.";
18
+ return (error.remediationAction ??
19
+ (error.resource === "transport"
20
+ ? "Export retained session evidence through export_evidence_bundle to a caller-selected path, or use complete CLI JSON output. Tools that accept retained-evidence references can inspect compatible records. The connection remains usable."
21
+ : error.resource === "cpu"
22
+ ? "Review the reported worker CPU limits and observed signal. Retry with sufficient CPU time or a smaller artifact; REA retains tighter inherited limits."
23
+ : error.resource === "file-size"
24
+ ? "Review the reported worker file-size limits and write failure. Retry with a sufficient file-size allowance for the evidence reply; REA retains tighter inherited limits."
25
+ : "Review the reported worker memory limits and available host memory. Retry with sufficient memory or a smaller artifact; REA retains tighter inherited limits."));
20
26
  if (error instanceof HopperTimeoutError)
21
- return error.providerState === "busy"
22
- ? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry."
23
- : "Check binary_session for Hopper health, then retry the operation.";
27
+ return error.operation === undefined
28
+ ? "Inspect Hopper for a loader or license dialog and review details.launcher. Correct the loader configuration or complete Hopper setup, then open the target again."
29
+ : error.providerState === "busy"
30
+ ? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry."
31
+ : "Check binary_session for Hopper health, then retry the operation.";
24
32
  if (error instanceof HopperProcessError)
25
- return "Check binary_session provider health. Restart the owned Hopper process only when it has stopped.";
33
+ return hopperProcessRemediation(error);
26
34
  if (error instanceof HopperStartError)
27
35
  return error.ownerRunId === undefined
28
36
  ? "Check the Hopper launcher and target details, then retry opening the target."
29
37
  : `Use the active REA session ${error.ownerRunId} or close it before opening this target again.`;
30
38
  if (error instanceof HopperRemoteError)
31
- return "Review the Hopper diagnostic details; correct the request or retry if the failure was transient.";
39
+ return error.diagnosticType === "invalid_request"
40
+ ? "Correct the reported address, document, or arguments and retry."
41
+ : "Review the Hopper diagnostic details; correct the request or retry if the failure was transient.";
32
42
  if (error instanceof EvidenceReferenceError)
33
43
  return "Use an exact Evidence reference retained by this session, supply the complete inline Evidence, re-run its producer, or import its Evidence bundle. close_binary clears retained records.";
34
44
  if (error instanceof BinaryTargetError &&
@@ -37,7 +47,7 @@ export const analysisErrorRemediationAction = (error) => {
37
47
  if (error instanceof AnalysisAccessDeniedError)
38
48
  return "Check the current process's read access to the selected path. Retry with a readable local file.";
39
49
  if (error instanceof AnalysisArtifactChangedError)
40
- return "Wait until the selected file is stable, then retry this operation.";
50
+ return "Wait until the selected file is stable. For an active binary session, reopen the target with open_binary before retrying so REA acquires its current identity; for a CLI command or target-free tool, rerun the operation.";
41
51
  if (error instanceof AnalysisInputError)
42
52
  return "Correct the listed arguments and retry.";
43
53
  if (error instanceof UnknownRegistryError && error.reason === "not-found")
@@ -51,7 +61,10 @@ export const analysisErrorCategory = (error) => {
51
61
  if (error._tag === "ProcessCaptureError")
52
62
  return error.userCategory ?? "execution_failure";
53
63
  if (error instanceof BrowserObservationError)
54
- return browserErrorCategory(error.reason);
64
+ return error.userCategory ?? browserErrorCategory(error.reason);
65
+ if (error instanceof HopperRemoteError &&
66
+ error.diagnosticType === "invalid_request")
67
+ return "invalid_input";
55
68
  if (error instanceof HopperRemoteError &&
56
69
  error.diagnosticType === "authorization")
57
70
  return "unavailable";
@@ -62,6 +75,10 @@ export const analysisErrorCategory = (error) => {
62
75
  return STATIC_ERROR_CATEGORIES[error._tag] ?? "execution_failure";
63
76
  };
64
77
  const browserErrorCategory = (reason) => {
78
+ if (reason === "cancelled")
79
+ return "cancelled";
80
+ if (reason === "timeout")
81
+ return "timeout";
65
82
  if (reason === "payload_limit")
66
83
  return "truncated";
67
84
  if (reason === "target_not_found" ||
@@ -100,6 +117,8 @@ const STATIC_ERROR_CATEGORIES = {
100
117
  BinaryTargetError: "unavailable",
101
118
  };
102
119
  export const analysisErrorUserMessage = (error) => {
120
+ if (error instanceof AnalysisSnapshotMismatchError)
121
+ return error.message;
103
122
  if (error instanceof AnalysisUnsupportedTargetError)
104
123
  return error.message;
105
124
  if (error instanceof AnalysisResourceConstraintError)
@@ -127,7 +146,7 @@ export const analysisErrorUserMessage = (error) => {
127
146
  if (error instanceof EvidenceIntegrityError)
128
147
  return "Evidence is invalid or has changed. Recreate or re-import it, then try again.";
129
148
  if (error instanceof EvidenceFileError)
130
- return evidenceFileMessage(error.reason);
149
+ return evidenceFileMessage(error);
131
150
  if (error instanceof UnknownRegistryError && error.reason === "not-found")
132
151
  return "The requested residual unknown does not exist in this session. Check the unknown_id and try again.";
133
152
  if (error instanceof UnknownRegistryError)
@@ -147,13 +166,15 @@ export const analysisErrorUserMessage = (error) => {
147
166
  };
148
167
  const hopperErrorUserMessage = (error) => {
149
168
  if (error instanceof HopperTimeoutError) {
150
- const request = error.operation ?? "startup";
169
+ if (error.operation === undefined)
170
+ return "REA timed out waiting for Hopper bridge readiness. Hopper may be waiting for a loader or license dialog; inspect its window and the captured launcher outcome before retrying.";
171
+ const request = error.operation;
151
172
  return error.providerState === "busy"
152
173
  ? `Hopper timed out during ${request} while the provider remained busy. Check binary_session.analysis_activity, wait for the active request to finish, then retry.`
153
174
  : `Hopper timed out during ${request} before it started. Check binary_session for provider health, then retry.`;
154
175
  }
155
176
  if (error instanceof HopperProcessError)
156
- return `Hopper stopped during ${error.operation ?? "connection"}${error.exitCode === null ? "; its exit was not observed" : ` with exit code ${String(error.exitCode)}`}.${error.userMessage === undefined ? "" : ` ${error.userMessage}`} Check binary_session provider health before retrying.`;
177
+ return hopperProcessMessage(error);
157
178
  if (error instanceof HopperStartError)
158
179
  return (error.userMessage ??
159
180
  "Hopper could not start. Check the launcher and target details, then retry opening the target.");
@@ -161,6 +182,36 @@ const hopperErrorUserMessage = (error) => {
161
182
  return `Hopper ${error.operation ?? "analysis"} failed (${String(error.code)}, ${error.diagnosticType}): ${error.safeMessage}`;
162
183
  return undefined;
163
184
  };
185
+ const RESTART_OWNED_PROVIDER = "Restart the owned provider by calling close_binary, then open the target again and retry.";
186
+ const hopperProcessRemediation = (error) => {
187
+ if (error.failureCode !== undefined && error.userMessage !== undefined)
188
+ return error.userMessage;
189
+ if (error.stage === "launch")
190
+ return "Review the captured launcher diagnostics and Hopper setup, then retry opening the target.";
191
+ if (providerRetryAction(error.providerState) === "restart_provider")
192
+ return RESTART_OWNED_PROVIDER;
193
+ return "Read binary_session.provider_operation_health for this request before retrying or restarting the owned provider.";
194
+ };
195
+ const hopperProcessMessage = (error) => {
196
+ const stage = error.stage;
197
+ const where = error.operation ?? stage;
198
+ const request = error.requestId === undefined
199
+ ? ""
200
+ : ` Request id ${String(error.requestId)}.`;
201
+ const startup = error.userMessage === undefined ? "" : ` ${error.userMessage}`;
202
+ if (error.providerState === "exited") {
203
+ const exit = error.exitCode === null
204
+ ? "no exit code was observed"
205
+ : `exit code ${String(error.exitCode)}`;
206
+ const recovery = error.failureCode === undefined && stage !== "launch"
207
+ ? ` ${RESTART_OWNED_PROVIDER}`
208
+ : "";
209
+ return `Hopper exited during ${where} (${exit}).${startup}${recovery}${request}`;
210
+ }
211
+ if (error.providerState === "unreachable")
212
+ return `Hopper became unreachable during ${where}; its process exit was not observed. ${RESTART_OWNED_PROVIDER}${startup}${request}`;
213
+ return `Hopper failed during ${where} and REA could not determine whether the provider is busy, exited, or unreachable.${startup} Read binary_session.provider_operation_health for this request before retrying or restarting.${request}`;
214
+ };
164
215
  const standardErrorMessage = (tag) => {
165
216
  if (UNREADABLE_OUTPUT_TAGS.has(tag))
166
217
  return "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.";
@@ -214,7 +265,11 @@ const artifactMessage = (reason) => {
214
265
  return "Artifact is invalid or has changed. Get a fresh copy and try again.";
215
266
  return "Artifact could not be read or written. Check file access and try again.";
216
267
  };
217
- const evidenceFileMessage = (reason) => {
268
+ const evidenceFileMessage = ({ operation, reason, }) => {
269
+ if (reason === "missing")
270
+ return operation === "read"
271
+ ? "Evidence file does not exist at the selected path. Check the path and try again."
272
+ : "Evidence output directory does not exist. Choose an existing directory and try again.";
218
273
  if (reason === "not-file")
219
274
  return "Evidence path does not point to a regular file. Choose a file and try again.";
220
275
  if (reason === "exists")
@@ -4,20 +4,40 @@ import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancel
4
4
  import { ArtifactOperationError } from "./artifactOperationError.js";
5
5
  import { BinaryTargetError } from "./configurationErrors.js";
6
6
  import { BrowserObservationError } from "./browserObservationError.js";
7
- import { EvidenceFileError, EvidenceReferenceError } from "./evidenceErrors.js";
8
- import { HopperCancelledError, HopperProcessError, HopperRemoteError, HopperTimeoutError, } from "./hopperErrors.js";
7
+ import { EvidenceFileError, EvidenceIntegrityError, EvidenceReferenceError, } from "./evidenceErrors.js";
8
+ import { HopperCancelledError, HopperProcessError, HopperRemoteError, HopperStartError, HopperTimeoutError, } from "./hopperErrors.js";
9
9
  import { ProviderAdapterError } from "./providerAdapterError.js";
10
10
  import { ProviderSelectionError } from "./providerSelectionError.js";
11
11
  import { UnknownRegistryError } from "./unknownRegistryError.js";
12
+ import { providerRetryAction } from "./providerOperationHealth.js";
12
13
  import {} from "./analysisErrorBase.js";
13
14
  /** Project expected failures into exhaustive, secret-safe caller fields. */
14
15
  export const projectAnalysisError = (error) => {
15
16
  assertKnownAnalysisErrorTag(error._tag);
16
- const code = errorCode(error);
17
+ const underlyingCode = underlyingErrorCode(error);
18
+ const code = error.cleanupIncomplete ? "cleanup_incomplete" : underlyingCode;
17
19
  const primaryDetails = errorDetails(error);
18
- const details = error.capturedOutput === undefined
19
- ? primaryDetails
20
- : { ...primaryDetails, captured_output: { ...error.capturedOutput } };
20
+ const details = {
21
+ ...primaryDetails,
22
+ ...(error.cleanupIncomplete
23
+ ? {
24
+ cleanup: "incomplete",
25
+ resources: [...error.cleanupResources],
26
+ ...(error.cleanup === undefined
27
+ ? {}
28
+ : { cleanup_reason: error.cleanup.reason }),
29
+ execution_failure: primaryDetails?.execution_failure ?? underlyingCode,
30
+ }
31
+ : {}),
32
+ ...(error.capturedOutput === undefined
33
+ ? {}
34
+ : { captured_output: { ...error.capturedOutput } }),
35
+ ...(error.partialObservation === undefined
36
+ ? {}
37
+ : {
38
+ partial_observation: jsonValueSchema.parse(error.partialObservation),
39
+ }),
40
+ };
21
41
  return {
22
42
  code,
23
43
  category: analysisErrorCategory(error),
@@ -26,18 +46,21 @@ export const projectAnalysisError = (error) => {
26
46
  remediation: {
27
47
  action: analysisErrorRemediationAction(error),
28
48
  },
29
- ...(details === undefined ? {} : { details }),
49
+ ...(Object.keys(details).length === 0 ? {} : { details }),
30
50
  };
31
51
  };
32
- const errorCode = (error) => {
33
- if (error.cleanupIncomplete)
34
- return "cleanup_incomplete";
52
+ const underlyingErrorCode = (error) => {
53
+ if (error instanceof HopperRemoteError &&
54
+ error.diagnosticType === "invalid_request")
55
+ return "invalid_request";
35
56
  if (error instanceof ProviderSelectionError)
36
57
  return error.reason === "provider_unavailable"
37
58
  ? "provider_unavailable"
38
59
  : "capability_unavailable";
39
60
  if (error instanceof BrowserObservationError)
40
- return browserErrorCode(error.reason);
61
+ return error.userCategory === "cancelled"
62
+ ? "cancelled"
63
+ : browserErrorCode(error.reason);
41
64
  if (error instanceof ArtifactOperationError)
42
65
  return artifactOperationCode(error);
43
66
  if (error instanceof EvidenceFileError)
@@ -49,6 +72,10 @@ const errorCode = (error) => {
49
72
  return staticErrorCode(error._tag);
50
73
  };
51
74
  const browserErrorCode = (reason) => {
75
+ if (reason === "cancelled")
76
+ return "cancelled";
77
+ if (reason === "timeout")
78
+ return "provider_timeout";
52
79
  if (reason === "payload_limit")
53
80
  return "truncated";
54
81
  if (reason === "target_not_found" ||
@@ -176,6 +203,8 @@ const requestErrorDetails = (error) => {
176
203
  expected: error.expected,
177
204
  actual: error.actual,
178
205
  };
206
+ if (error instanceof EvidenceIntegrityError)
207
+ return { reason: error.message };
179
208
  return undefined;
180
209
  };
181
210
  const artifactStateErrorDetails = (error) => {
@@ -196,7 +225,11 @@ const artifactStateErrorDetails = (error) => {
196
225
  if (error instanceof UnknownRegistryError)
197
226
  return { reason: error.reason };
198
227
  if (error instanceof EvidenceFileError)
199
- return { operation: error.operation, reason: error.reason };
228
+ return {
229
+ operation: error.operation,
230
+ reason: error.reason,
231
+ ...(error.path === undefined ? {} : { path: error.path }),
232
+ };
200
233
  return undefined;
201
234
  };
202
235
  const providerErrorDetails = (error) => {
@@ -257,10 +290,13 @@ const providerErrorDetails = (error) => {
257
290
  ...(error.operation === undefined ? {} : { operation: error.operation }),
258
291
  ...(error.requestId === undefined ? {} : { request_id: error.requestId }),
259
292
  };
260
- if (error instanceof HopperProcessError)
293
+ if (error instanceof HopperProcessError) {
294
+ const stage = error.stage;
261
295
  return {
262
296
  exit_code: error.exitCode,
263
- stage: error.operation === undefined ? "connection" : "analysis",
297
+ stage,
298
+ provider_state: error.providerState,
299
+ retry_action: providerRetryAction(error.providerState, error.failureCode !== undefined || error.stage === "launch"),
264
300
  ...(error.failureCode === undefined
265
301
  ? {}
266
302
  : { failure_code: error.failureCode }),
@@ -269,6 +305,22 @@ const providerErrorDetails = (error) => {
269
305
  ...(error.diagnostic === undefined
270
306
  ? {}
271
307
  : { diagnostics: { ...error.diagnostic } }),
308
+ ...(error.launcherFailure === undefined
309
+ ? {}
310
+ : { launcher: error.launcherFailure }),
311
+ };
312
+ }
313
+ if (error instanceof HopperStartError)
314
+ return {
315
+ stage: "launch",
316
+ provider_state: "unknown",
317
+ retry_action: error.ownerRunId === undefined ? "retry" : "unknown",
318
+ ...(error.ownerRunId === undefined
319
+ ? {}
320
+ : { owner_run_id: error.ownerRunId }),
321
+ ...(error.launcherFailure === undefined
322
+ ? {}
323
+ : { launcher: error.launcherFailure }),
272
324
  };
273
325
  return undefined;
274
326
  };
@@ -290,16 +342,40 @@ const primaryBrowserFailureReason = (error) => {
290
342
  };
291
343
  const lifecycleErrorDetails = (error) => {
292
344
  if (error instanceof AnalysisCancelledError)
293
- return { operation: error.operation, cleanup: "complete" };
345
+ return {
346
+ operation: error.operation,
347
+ cleanup: error.cleanup === undefined ? "complete" : "incomplete",
348
+ ...(error.cleanup === undefined
349
+ ? {}
350
+ : {
351
+ cleanup_reason: error.cleanup.reason,
352
+ resources: [...error.cleanup.resources],
353
+ execution_failure: "cancelled",
354
+ }),
355
+ };
294
356
  if (error instanceof HopperCancelledError)
295
357
  return { operation: "hopper", cleanup: "complete" };
296
358
  if (error instanceof AnalysisTimeoutError)
297
- return { operation: error.operation, timeout_ms: error.timeoutMs };
359
+ return {
360
+ operation: error.operation,
361
+ timeout_ms: error.timeoutMs,
362
+ ...(error.cleanup === undefined
363
+ ? {}
364
+ : {
365
+ cleanup: "incomplete",
366
+ cleanup_reason: error.cleanup.reason,
367
+ resources: [...error.cleanup.resources],
368
+ }),
369
+ };
298
370
  if (error instanceof HopperTimeoutError)
299
371
  return {
300
- stage: error.operation === undefined ? "startup" : "analysis",
372
+ stage: error.operation === undefined ? "startup" : error.stage,
301
373
  timeout_ms: error.timeoutMs,
374
+ ...(error.launcherOutcome === undefined
375
+ ? {}
376
+ : { launcher: error.launcherOutcome }),
302
377
  provider_state: error.providerState,
378
+ retry_action: error.providerState === "busy" ? "wait" : "retry",
303
379
  ...(error.operation === undefined ? {} : { operation: error.operation }),
304
380
  ...(error.requestId === undefined ? {} : { request_id: error.requestId }),
305
381
  };
@@ -313,18 +389,21 @@ const lifecycleErrorDetails = (error) => {
313
389
  ...(error.executionFailure === undefined
314
390
  ? {}
315
391
  : { execution_failure: error.executionFailure }),
316
- ...(error.partialObservation === undefined
392
+ };
393
+ if (error._tag === "ProcessCaptureError") {
394
+ const details = {
395
+ ...(error.userCategory === "cancelled"
396
+ ? { operation: "process_capture", cleanup: "complete" }
397
+ : {}),
398
+ ...(error.cleanupReport === undefined
317
399
  ? {}
318
- : {
319
- partial_observation: jsonValueSchema.parse(error.partialObservation),
320
- }),
400
+ : { cleanup_report: jsonValueSchema.parse(error.cleanupReport) }),
401
+ ...(error.executionFailure === undefined
402
+ ? {}
403
+ : { execution_failure: error.executionFailure }),
321
404
  };
322
- if (error._tag === "ProcessCaptureError" &&
323
- error.userCategory === "cancelled")
324
- return { operation: "process_capture", cleanup: "complete" };
325
- if (error._tag === "ProcessCaptureError" &&
326
- error.executionFailure !== undefined)
327
- return { execution_failure: error.executionFailure };
405
+ return Object.keys(details).length === 0 ? undefined : details;
406
+ }
328
407
  if (error instanceof BinaryTargetError)
329
408
  return {
330
409
  path: error.path,
@@ -1,9 +1,7 @@
1
1
  import { z } from "zod";
2
+ import { localPathStringSchema } from "../localPath.js";
2
3
  const target = {
3
- path: z
4
- .string()
5
- .min(1)
6
- .describe("Local APK path; the target is never executed"),
4
+ path: localPathStringSchema.describe("Local APK path; the target is never executed"),
7
5
  };
8
6
  const classTarget = {
9
7
  ...target,
@@ -5,6 +5,7 @@ import { parseArtifactInventoryEvidence } from "../artifactInventoryEvidence.js"
5
5
  import { evidenceSchema } from "../evidence.js";
6
6
  import { digestSchema } from "../digests.js";
7
7
  import { prefixedDigestSchema } from "../digests.js";
8
+ import { bridgeCandidateCoverageSchema, projectCartesianCandidates, } from "../bridgeCandidateProjection.js";
8
9
  const evidenceIdSchema = prefixedDigestSchema("ev");
9
10
  const pathSchema = z.string().min(1);
10
11
  const componentSchema = z.strictObject({
@@ -52,6 +53,7 @@ export const androidApplicationProjectionResultSchema = z.strictObject({
52
53
  "unity-convention",
53
54
  ]),
54
55
  })),
56
+ bridge_candidate_coverage: bridgeCandidateCoverageSchema,
55
57
  coverage: z.strictObject({
56
58
  status: z.enum(["complete-within-inventory", "partial"]),
57
59
  inventory_complete: z.boolean(),
@@ -88,6 +90,11 @@ export const projectAndroidApplication = (input) => {
88
90
  "Manifest, resource, signing, and bytecode semantics require a dedicated Android provider; this projection reports exact inventory paths and hashes only.",
89
91
  "Runtime families are inferred from inventory formats and paths; filename suffixes do not establish valid DEX or JVM class bytes.",
90
92
  "Bridge candidates are path-based hypotheses, not decoded JNI declarations or observed runtime calls.",
93
+ ...(bridgeProjection.coverage.status === "partial"
94
+ ? [
95
+ `Bridge candidate pairs exceeded the projection safety budget; ${bridgeProjection.coverage.omitted_candidates} hypotheses are omitted. Component arrays still include every component from the supplied inventory pages.`,
96
+ ]
97
+ : []),
91
98
  ];
92
99
  const withoutId = {
93
100
  root_sha256: inventory.manifest.root_sha256,
@@ -98,8 +105,9 @@ export const projectAndroidApplication = (input) => {
98
105
  components,
99
106
  runtime_families: runtimeFamilies(all),
100
107
  bridge_candidates: bridgeProjection.candidates,
108
+ bridge_candidate_coverage: bridgeProjection.coverage,
101
109
  coverage: {
102
- status: inventory.complete
110
+ status: inventory.complete && bridgeProjection.coverage.status === "complete"
103
111
  ? "complete-within-inventory"
104
112
  : "partial",
105
113
  inventory_complete: inventory.complete,
@@ -141,14 +149,14 @@ const runtimeFamilies = (all) => {
141
149
  return [...families].sort(compare);
142
150
  };
143
151
  const bridgeCandidates = (managed, native) => {
144
- const candidates = managed.flatMap((source) => native.map((target) => ({
145
- managed_path: source.path,
146
- native_path: target.path,
147
- basis: bridgeBasis(target.path),
148
- })));
149
- return {
150
- candidates,
151
- };
152
+ return projectCartesianCandidates({
153
+ groups: [{ left: managed, right: native }],
154
+ createCandidate: (managed_path, target) => ({
155
+ managed_path,
156
+ native_path: target.path,
157
+ basis: bridgeBasis(target.path),
158
+ }),
159
+ });
152
160
  };
153
161
  const bridgeBasis = (path) => {
154
162
  const lower = path.toLowerCase();